lunny/git-lfs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e2cf4140f3
git-lfs/docs/api.md
Rick Olson e2cf4140f3 update with details on PUT redirections
2015-01-08 12:05:24 -07:00

5.3 KiB
Raw Blame History

Git Media 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 specification 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.

GET objects/{oid}

This gets either the object content, or the object's meta data. The OID is the value from the object pointer.

Getting the content

To download the object content, send an Accept header of application/vnd.git-media. The server returns the raw content back with a Content-Type of application/octet-stream.

> GET objects/{oid} HTTP/1.1
> Accept: application/vnd.git-media
> Authorization: Basic ... (if authentication is needed)
>
< HTTP/1.1 200 OK
< Content-Type: application/octet-stream
<
< {binary contents}

The server can also redirect to another location. This is useful in cases where you do not want to render user content on a domain with important cookies.
Request headers like Range or Accept should be passed through. The Authorization header must not be passed through if the location's host or scheme differs from the original request uri.

> GET objects/{oid} HTTP/1.1
> Accept: application/vnd.git-media
> Authorization: Basic ... (if authentication is needed)
>
< HTTP/1.1 302 Found
< Location: https://some-other-site.com/{oid}
<
< {binary contents}

Responses

  • 200 - The object contents or meta data is in the response.
  • 302 - Temporary redirect to a new location.
  • 404 - The user does not have access to the object, or it does not exist.

Getting meta data.

You can also request just the JSON meta data with an Accept header of application/vnd.git-media+json.

> GET objects/{OID} HTTP/1.1
> Accept: application/vnd.git-media+json
> Authorization: Basic ... (if authentication is needed)
>
< HTTP/1.1 200 OK
< Content-Type: application/vnd.git-media+json
<
< {
<   "oid": "the-sha-256-signature",
<   "size": 123456,
<   "md5": "the-md5-signature",
<   "sha1": "the-sha1-signature"
< }

The oid and size properties are required. The server can extend the output with custom properties.

PUT objects/{oid}

This writes the object contents to the Git Media server.

> PUT objects/{oid} HTTP/1.1
> Accept: application/vnd.git-media
> Content-Type: application/octet-stream
> Authorization: Basic ...
> Content-Length: 123
>
> {binary contents}
>
< HTTP/1.1 200 OK

Responses

  • 200 - The object already exists.

  • 201 - The object was uploaded successfully.

  • 307 - The server is returning a different location to send the object. Clients should retry the PUT against the URL. See the Redirection section below.

    The Authorization header must not be passed through if the location's host or scheme differs from the original request uri.

  • 409 - The object contents do not match the OID.

  • 403 - The user has read, but not write access.

  • 404 - The repository does not exist for the user.

PUT Redirection

The Git Media API supports offloading storage concerns to a separate storage API. In addition to a 307 response, the Git Media API needs to return one or more headers so the client knows how to retry the request.

  • Location (required) - This is an absolute URL of the new location to send the object.
  • Git-Media-Callback (optional) - This is an absolute URL of a location to POST with the success or failure of the redirected request.
  • Git-Media-Set-* (optional) - Instruct the Git Media client for setting other headers by setting response headers with this prefix.
Example client request
> PUT https://git-media-server.com/objects/{oid}
> Accept: application/vnd.git-media
> Content-Type: application/octet-stream
> Authorization: Basic ...
> Content-Length: 123
>
> {binary contents}
>
< HTTP/1.1 307 Temporary Redirect
< Location: https://simple-storage-service.com/objects/{oid}
< Git-Media-Callback: https://git-media-server.com/callback
< Git-Media-Set-Authorization: simple-storage-service-authentication-token
Example client redirection
> PUT https://simple-storage-service.com/objects/{oid}
> Authorization: simple-storage-service-authentication-token
> Content-Type: application/octet-stream
> Content-Length: 123
Example client callback

The client callback is only made if the 307 redirection returned a Git-Media-Callback header. The Git Media client then makes a POST to that URL with:

  • 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
> Content-Length: 123
>
> {"oid": "{oid}", "status": 200, "body": "ok"}

OPTIONS objects/{oid}

This is a pre-flight request to verify credentials before sending the file contents.

> OPTIONS objects/{oid} HTTP/1.1
> Accept: application/vnd.git-media
> Authorization: Basic ...
>
< HTTP/1.1 200 OK
  • 200 - The user is able to send the object but the server already has it.
  • 204 - The user is able to send the object and the server does not have it.
  • 403 - The user has read, but not write access.
  • 404 - The repository does not exist for the user.