lunny/git-lfs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Start rename in the specs

Browse Source
This commit is contained in:
rubyist 2015-01-30 10:35:57 -05:00
parent 776a3e975b
commit cc6d5a5ae3
2 changed files with 45 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
docs/api.md
View File

@ -1,11 +1,11 @@
# Git Media API
# Hawser API
The server implements a simple API for uploading and downloading binary content.
Git repositories that use Git Media will specify a URI endpoint. See the
Git repositories that use Hawser will specify a URI endpoint. See the
[specification](spec.md) for how Git Media determines the server endpoint to use.
Use that endpoint as a base, and append the following relative paths to upload
and download from the Git Media server.
and download from the Hawser server.
## GET /objects/{oid}
@ -14,12 +14,12 @@ value from the object pointer.
### Getting the content
To download the object content, send an Accept header of `application/vnd.git-media`.
To download the object content, send an Accept header of `application/vnd.hawser`.
The server returns the raw content back with a `Content-Type` of
`application/octet-stream`.
```
> GET https://git-media-server.com/objects/{oid} HTTP/1.1
> GET https://hawser-server.com/objects/{oid} HTTP/1.1
> Accept: application/octet-stream
> Authorization: Basic ... (if authentication is needed)
>
@ -36,8 +36,8 @@ Request headers like `Range` or `Accept` should be passed through. The
scheme differs from the original request uri.
```
> GET https://git-media-server.com/objects/{oid} HTTP/1.1
> Accept: application/vnd.git-media
> GET https://hawser-server.com/objects/{oid} HTTP/1.1
> Accept: application/vnd.hawser
> Authorization: Basic ... (if authentication is needed)
>
< HTTP/1.1 302 Found
@ -55,15 +55,15 @@ scheme differs from the original request uri.
### Getting meta data.
You can also request just the JSON meta data with an `Accept` header of
`application/vnd.git-media+json`. Here's an example successful request:
`application/vnd.hawser+json`. Here's an example successful request:
```
> GET https://git-media-server.com/objects/{OID} HTTP/1.1
> Accept: application/vnd.git-media+json
> GET https://hawser-server.com/objects/{OID} HTTP/1.1
> Accept: application/vnd.hawser+json
> Authorization: Basic ... (if authentication is needed)
>
< HTTP/1.1 200 OK
< Content-Type: application/vnd.git-media+json
< Content-Type: application/vnd.hawser+json
<
< {
< "oid": "the-sha-256-signature",
@ -88,12 +88,12 @@ used with the `download` relation.
Here's a sample response for a request with an authorization error:
```
> GET https://git-media-server.com/objects/{OID} HTTP/1.1
> Accept: application/vnd.git-media+json
> GET https://hawser-server.com/objects/{OID} HTTP/1.1
> Accept: application/vnd.hawser+json
> Authorization: Basic ... (if authentication is needed)
>
< HTTP/1.1 404 Not found
< Content-Type: application/vnd.git-media+json
< Content-Type: application/vnd.hawser+json
<
< {
< "message": "Not found"
@ -109,15 +109,15 @@ access to it.
## OPTIONS /objects/{oid}
This is a pre-flight request to verify credentials before sending the file
contents. Note: The `OPTIONS` method is only supported in pre-1.0 Git Media
contents. Note: The `OPTIONS` method is only supported in pre-1.0 Hawser
clients. After 1.0, clients should use the `GET` with the
`application/vnd.git-media+json` Accept header.
`application/vnd.hawser+json` Accept header.
Here's an example successful request:
```
> OPTIONS https://git-media-server.com/objects/{OID} HTTP/1.1
> Accept: application/vnd.git-media+json
> OPTIONS https://hawser-server.com/objects/{OID} HTTP/1.1
> Accept: application/vnd.hawser+json
> Authorization: Basic ... (if authentication is needed)
>
< HTTP/1.1 200 OK
@ -131,7 +131,7 @@ There are what the HTTP status codes mean:
* 204 - The user is able to PUT the object to the same URL.
* 403 - The user has **read**, but not **write** access.
* 404 - The repository does not exist for the user.
* 405 - OPTIONS not supported, use a GET request with a `application/vnd.git-media+json`
* 405 - OPTIONS not supported, use a GET request with a `application/vnd.hawser+json`
Accept header.
## POST /objects
@ -140,9 +140,9 @@ This request initiates the upload of an object, given a JSON body with the oid
and size of the object to upload.
```
> POST https://git-media-server.com/objects/ HTTP/1.1
> Accept: application/vnd.git-media+json
> Content-Type: application/vnd.git-media+json
> POST https://hawser-server.com/objects/ HTTP/1.1
> Accept: application/vnd.hawser+json
> Content-Type: application/vnd.hawser+json
> Authorization: Basic ... (if authentication is needed)
>
> {
@ -151,7 +151,7 @@ and size of the object to upload.
> }
>
< HTTP/1.1 201 Created
< Content-Type: application/vnd.git-media+json
< Content-Type: application/vnd.hawser+json
<
< {
< "_links": {
@ -192,8 +192,8 @@ successfully uploading an object.
This writes the object contents to the Git Media server.
```
> PUT https://git-media-server.com/objects/{oid} HTTP/1.1
> Accept: application/vnd.git-media
> PUT https://hawser-server.com/objects/{oid} HTTP/1.1
> Accept: application/vnd.hawser
> Content-Type: application/octet-stream
> Authorization: Basic ...
> Content-Length: 123
@ -214,19 +214,19 @@ get the current URL to send a file.
## Callbacks
When Git Media clients issue a POST request to initiate an object upload, the
response can potentially return a "callback" link relation. If given, The Git
Media server expects a POST to the callback href after a successful upload. Git
Media clients send:
When Hawser clients issue a POST request to initiate an object upload, the
response can potentially return a "callback" link relation. If given, The Hawser
server expects a POST to the callback href after a successful upload. Hawser
clients send:
* `oid` - The String OID of the Git Media object.
* `status` - The HTTP status of the redirected PUT request.
* `body` - The response body from the redirected PUT request.
```
> POST https://git-media-server.com/callback
> Accept: application/vnd.git-media
> Content-Type: application/vnd.git-media+json
> POST https://hawser-server.com/callback
> Accept: application/vnd.hawser
> Content-Type: application/vnd.hawser+json
> Content-Length: 123
>
> {"oid": "{oid}", "status": 200, "body": "ok"}

26
docs/spec.md
View File

@ -1,16 +1,16 @@
# Git Media Specification
# Hawser Specification
This is a general guide for Git Media clients. Typically it should be
implemented by a command line `git-media` tool, but the details may be useful
This is a general guide for Hawser clients. Typically it should be
implemented by a command line `git-hawser` tool, but the details may be useful
for other tools.
## The Pointer
The core Git Media idea is that instead of writing large blobs to a Git repository,
The core Hawser idea is that instead of writing large blobs to a Git repository,
only a pointer file is written.
```
version http://git-media.io/v/2
version http://hawser.github.com/spec/v1
oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
size 12345
(ending \n)
@ -24,7 +24,7 @@ translate to the same Git blob OID. This means:
* Use properties "version", "oid", and "size" in that order.
* Separate the property from its value with a single space.
* Oid has a "sha256:" prefix. No other hashing methods are currently supported
for Git Media oids.
for Hawser oids.
* Size is in bytes.
Note: Earlier versions only contained the OID, with a `# comment` above it.
@ -47,7 +47,7 @@ generated from the SHA-256 signature of the file's contents.
## The Server
Git Media needs a URL endpoint to talk to a remote server. A Git repository
Hawser needs a URL endpoint to talk to a remote server. A Git repository
can have different media endpoints for different remotes. Here is the list
of rules that Git Media uses to determine a repository's Git Media server:
@ -69,16 +69,16 @@ options:
media = "https://github.com/github/assets-team/info/media"
```
Git Media uses `git credential` to fetch credentials for HTTPS requests. Setup
Hawser uses `git credential` to fetch credentials for HTTPS requests. Setup
a credential cache helper to save passwords for future users.
## Intercepting Git
Git Media uses the `clean` and `smudge` filters to decide which files use
Git Media. The global filters can be set up with `git media init`:
Hawser uses the `clean` and `smudge` filters to decide which files use
Hawser. The global filters can be set up with `git hawser init`:
```
$ git media init
$ git hawser init
```
The `clean` filter runs as files are added to repositories. Git sends the
@ -95,7 +95,7 @@ signature.
* Write the pointer file to STDOUT.
Note that the `clean` filter does not push the file to the server. Use the
`git media sync` command to do that.
`git hawser sync` command to do that.
The `smudge` filter runs as files are being checked out from the Git repository
to the working directory. Git sends the content of the Git blob as STDIN, and
@ -117,4 +117,4 @@ $ cat .gitattributes
*.zip filter=media -crlf
```
Use the `git media path` command to view and add to `.gitattributes`.
Use the `git hawser path` command to view and add to `.gitattributes`.