2015-03-19 19:30:55 +00:00
|
|
|
# Git LFS API
|
2014-06-02 14:03:37 +00:00
|
|
|
|
|
|
|
The server implements a simple API for uploading and downloading binary content.
|
2015-03-19 19:30:55 +00:00
|
|
|
Git repositories that use Git LFS will specify a URI endpoint. See the
|
2014-06-02 14:03:37 +00:00
|
|
|
[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
|
2015-03-19 19:30:55 +00:00
|
|
|
and download from the Git LFS server.
|
2014-06-02 14:03:37 +00:00
|
|
|
|
2015-03-19 19:30:55 +00:00
|
|
|
All requests should send an Accept header of `application/vnd.git-lfs+json`.
|
2015-02-27 00:00:50 +00:00
|
|
|
This may change in the future as the API evolves.
|
2014-12-18 00:55:13 +00:00
|
|
|
|
2015-03-19 16:53:01 +00:00
|
|
|
## API Responses
|
|
|
|
|
|
|
|
This specification defines what status codes that API can return. Look at each
|
|
|
|
individual API method for more details. Some of the specific status codes may
|
|
|
|
trigger specific error messages from the client.
|
|
|
|
|
|
|
|
* 200 - The request completed successfully.
|
|
|
|
* 202 - An upload request has been accepted. Clients should follow hypermedia
|
|
|
|
links to actually upload the content.
|
2015-03-19 16:58:23 +00:00
|
|
|
* 400 - General error with the client's request. Invalid JSON formatting, for
|
|
|
|
example.
|
2015-03-19 16:53:01 +00:00
|
|
|
* 401 - The authentication credentials are incorrect.
|
|
|
|
* 403 - The requesting user has access to see the repository, but not to push
|
|
|
|
changes to it.
|
|
|
|
* 404 - Either the user does not have access to see the repository, or the
|
|
|
|
repository or requested object does not exist.
|
|
|
|
|
|
|
|
The following status codes can optionally be returned from the API, depending on
|
2015-03-19 16:58:23 +00:00
|
|
|
the server implementation.
|
2015-03-19 16:53:01 +00:00
|
|
|
|
2015-03-19 19:30:55 +00:00
|
|
|
* 406 - The Accept header is invalid. It should be `application/vnd.git-lfs+json`.
|
2015-03-19 16:53:01 +00:00
|
|
|
* 429 - The user has hit a rate limit with the server. Though the API does not
|
|
|
|
specify any rate limits, implementors are encouraged to set some for
|
|
|
|
availability reasons.
|
|
|
|
* 501 - The server has not implemented the current method. Reserved for future
|
|
|
|
use.
|
|
|
|
* 509 - Returned if the bandwidth limit for the user or repository has been
|
|
|
|
exceeded. The API does not specify any bandwidth limit, but implementors may
|
|
|
|
track usage.
|
|
|
|
|
|
|
|
Some server errors may trigger the client to retry requests, such as 500, 502,
|
|
|
|
503, and 504.
|
|
|
|
|
2015-03-19 16:58:23 +00:00
|
|
|
If the server returns a JSON error object, the client can display this message
|
|
|
|
to users.
|
|
|
|
|
|
|
|
```
|
2015-03-19 19:30:55 +00:00
|
|
|
> GET https://git-lfs-server.com/objects/{OID} HTTP/1.1
|
|
|
|
> Accept: application/vnd.git-lfs+json
|
2015-03-19 16:58:23 +00:00
|
|
|
>
|
|
|
|
< HTTP/1.1 200 OK
|
2015-03-19 19:30:55 +00:00
|
|
|
< Content-Type: application/vnd.git-lfs+json
|
2015-03-19 16:58:23 +00:00
|
|
|
<
|
|
|
|
< {
|
|
|
|
< "message": "Bad credentials",
|
2015-03-19 19:30:55 +00:00
|
|
|
< "documentation_url": "https://git-lfs-server.com/docs/errors",
|
2015-03-19 17:19:50 +00:00
|
|
|
< "request_id": "123"
|
2015-03-19 16:58:23 +00:00
|
|
|
< }
|
|
|
|
```
|
|
|
|
|
2015-03-19 17:19:50 +00:00
|
|
|
The `documentation_url` and `request_id` properties are optional. If given,
|
|
|
|
they are displayed to the user.
|
2015-03-19 16:58:23 +00:00
|
|
|
|
2015-02-27 00:00:50 +00:00
|
|
|
## Hypermedia
|
2014-12-18 00:55:13 +00:00
|
|
|
|
2015-03-19 19:30:55 +00:00
|
|
|
The Git LFS API uses hypermedia hints to instruct the client what to do next.
|
2015-02-27 00:00:50 +00:00
|
|
|
These links are included in a `_links` property. Possible relations for objects
|
|
|
|
include:
|
2014-12-18 00:55:13 +00:00
|
|
|
|
2015-02-27 18:21:58 +00:00
|
|
|
* `self` - This points to the object's canonical API URL.
|
2015-02-27 00:00:50 +00:00
|
|
|
* `download` - Follow this link with a GET and the optional header values to
|
|
|
|
download the object content.
|
|
|
|
* `upload` - Upload the object content to this link with a PUT.
|
|
|
|
* `verify` - Optional link for the client to POST after an upload. If
|
|
|
|
included, the client assumes this step is required after uploading an object.
|
|
|
|
See the "Verification" section below for more.
|
2014-12-18 00:55:13 +00:00
|
|
|
|
2015-02-27 00:00:50 +00:00
|
|
|
Link relations specify the `href`, and optionally a collection of header values
|
|
|
|
to set for the request. These are optional, and depend on the backing object
|
2015-03-19 19:30:55 +00:00
|
|
|
store that the Git LFS API is using.
|
2014-06-02 14:03:37 +00:00
|
|
|
|
2015-03-19 19:30:55 +00:00
|
|
|
The Git LFS client will automatically send the same credentials to the followed
|
2015-02-27 00:00:50 +00:00
|
|
|
link relation as Basic Authentication IF:
|
2014-06-02 14:03:37 +00:00
|
|
|
|
2015-03-19 19:30:55 +00:00
|
|
|
* The url scheme, host, and port all match the Git LFS API endpoint's.
|
2015-02-27 00:00:50 +00:00
|
|
|
* The link relation does not specify an Authorization header.
|
2014-12-18 00:55:13 +00:00
|
|
|
|
2015-03-19 19:30:55 +00:00
|
|
|
If the host name is different, the Git LFS API needs to send enough information
|
2015-02-27 00:00:50 +00:00
|
|
|
through the href query or header values to authenticate the request.
|
2014-06-02 14:03:37 +00:00
|
|
|
|
2015-03-19 19:30:55 +00:00
|
|
|
The Git LFS client expects a 200 or 201 response from these hypermedia requests.
|
2015-03-19 16:53:01 +00:00
|
|
|
Any other response code is treated as an error.
|
|
|
|
|
2015-02-27 00:00:50 +00:00
|
|
|
## GET /objects/{oid}
|
2014-06-02 14:03:37 +00:00
|
|
|
|
2015-02-27 00:00:50 +00:00
|
|
|
This gets the object's meta data. The OID is the value from the object pointer.
|
2014-06-02 14:03:37 +00:00
|
|
|
|
|
|
|
```
|
2015-03-19 19:30:55 +00:00
|
|
|
> GET https://git-lfs-server.com/objects/{OID} HTTP/1.1
|
|
|
|
> Accept: application/vnd.git-lfs+json
|
2014-06-02 14:03:37 +00:00
|
|
|
> Authorization: Basic ... (if authentication is needed)
|
|
|
|
>
|
|
|
|
< HTTP/1.1 200 OK
|
2015-03-19 19:30:55 +00:00
|
|
|
< Content-Type: application/vnd.git-lfs+json
|
2014-06-02 14:03:37 +00:00
|
|
|
<
|
|
|
|
< {
|
|
|
|
< "oid": "the-sha-256-signature",
|
2014-12-18 00:55:13 +00:00
|
|
|
< "size": 123456,
|
2015-01-12 18:20:25 +00:00
|
|
|
< "_links": {
|
2015-02-27 00:00:50 +00:00
|
|
|
< "self": {
|
2015-03-19 19:30:55 +00:00
|
|
|
< "href": "https://git-lfs-server.com/objects/OID",
|
2015-02-27 00:00:50 +00:00
|
|
|
< },
|
2015-01-12 18:20:25 +00:00
|
|
|
< "download": {
|
|
|
|
< "href": "https://some-download.com",
|
|
|
|
< "header": {
|
|
|
|
< "Key": "value"
|
|
|
|
< }
|
|
|
|
< }
|
|
|
|
< }
|
2014-06-02 14:03:37 +00:00
|
|
|
< }
|
|
|
|
```
|
|
|
|
|
2015-01-13 23:58:51 +00:00
|
|
|
The `oid` and `size` properties are required. A hypermedia `_links` section is
|
2015-02-27 18:20:38 +00:00
|
|
|
included with a `download` link relation. Clients can follow this link to
|
|
|
|
access the object content. See the "Hypermedia" section above for more.
|
2015-01-12 18:20:25 +00:00
|
|
|
|
|
|
|
Here's a sample response for a request with an authorization error:
|
|
|
|
|
|
|
|
```
|
2015-03-19 19:30:55 +00:00
|
|
|
> GET https://git-lfs-server.com/objects/{OID} HTTP/1.1
|
|
|
|
> Accept: application/vnd.git-lfs+json
|
2015-01-12 18:20:25 +00:00
|
|
|
> Authorization: Basic ... (if authentication is needed)
|
|
|
|
>
|
2015-01-13 20:49:18 +00:00
|
|
|
< HTTP/1.1 404 Not found
|
2015-03-19 19:30:55 +00:00
|
|
|
< Content-Type: application/vnd.git-lfs+json
|
2015-01-12 18:20:25 +00:00
|
|
|
<
|
|
|
|
< {
|
2015-01-13 20:49:18 +00:00
|
|
|
< "message": "Not found"
|
2015-01-12 18:20:25 +00:00
|
|
|
< }
|
|
|
|
```
|
|
|
|
|
2015-02-27 00:00:50 +00:00
|
|
|
### Responses
|
2015-01-12 18:20:25 +00:00
|
|
|
|
2015-02-27 18:20:38 +00:00
|
|
|
* 200 - The object exists and the user has access to download it.
|
2015-03-19 16:53:01 +00:00
|
|
|
* 401 - The authentication credentials are incorrect.
|
2015-02-27 00:00:50 +00:00
|
|
|
* 404 - The user does not have access to the object, or it does not exist.
|
2015-01-12 18:20:25 +00:00
|
|
|
|
2015-01-13 23:58:51 +00:00
|
|
|
## POST /objects
|
|
|
|
|
|
|
|
This request initiates the upload of an object, given a JSON body with the oid
|
|
|
|
and size of the object to upload.
|
|
|
|
|
|
|
|
```
|
2015-03-19 19:30:55 +00:00
|
|
|
> POST https://git-lfs-server.com/objects/ HTTP/1.1
|
|
|
|
> Accept: application/vnd.git-lfs+json
|
|
|
|
> Content-Type: application/vnd.git-lfs+json
|
2015-01-13 23:58:51 +00:00
|
|
|
> Authorization: Basic ... (if authentication is needed)
|
|
|
|
>
|
|
|
|
> {
|
|
|
|
> "oid": "1111111",
|
|
|
|
> "size": 123
|
|
|
|
> }
|
|
|
|
>
|
2015-02-13 18:53:35 +00:00
|
|
|
< HTTP/1.1 202 Accepted
|
2015-03-19 19:30:55 +00:00
|
|
|
< Content-Type: application/vnd.git-lfs+json
|
2015-01-13 23:58:51 +00:00
|
|
|
<
|
|
|
|
< {
|
|
|
|
< "_links": {
|
|
|
|
< "upload": {
|
|
|
|
< "href": "https://some-upload.com",
|
|
|
|
< "header": {
|
|
|
|
< "Key": "value"
|
|
|
|
< }
|
|
|
|
< },
|
2015-02-13 18:53:35 +00:00
|
|
|
< "verify": {
|
2015-01-13 23:58:51 +00:00
|
|
|
< "href": "https://some-callback.com",
|
|
|
|
< "header": {
|
|
|
|
< "Key": "value"
|
|
|
|
< }
|
|
|
|
< }
|
|
|
|
< }
|
|
|
|
< }
|
|
|
|
```
|
|
|
|
|
|
|
|
A response can include one of multiple link relations, each with an `href`
|
|
|
|
property and an optional `header` property.
|
|
|
|
|
2015-03-10 20:24:41 +00:00
|
|
|
* `upload` - This relation describes how to upload the object. Expect this with
|
|
|
|
a 202 status.
|
2015-02-13 18:53:35 +00:00
|
|
|
* `verify` - The server can specify a URL for the client to hit after
|
2015-03-10 20:24:41 +00:00
|
|
|
successfully uploading an object. This is an optional relation for a 202
|
|
|
|
status.
|
|
|
|
* `download` - This relation describes how to download the object content. This
|
|
|
|
only appears on a 200 status.
|
2015-01-13 23:58:51 +00:00
|
|
|
|
|
|
|
### Responses
|
|
|
|
|
|
|
|
* 200 - The object already exists. Don't bother re-uploading.
|
2015-02-27 00:00:50 +00:00
|
|
|
* 202 - The object is ready to be uploaded. Follow the "upload" and optional
|
2015-02-13 18:53:35 +00:00
|
|
|
"verify" links.
|
2015-03-19 16:53:01 +00:00
|
|
|
* 401 - The authentication credentials are incorrect.
|
2015-01-13 23:58:51 +00:00
|
|
|
* 403 - The user has **read**, but not **write** access.
|
|
|
|
* 404 - The repository does not exist for the user.
|
|
|
|
|
2015-02-13 18:53:35 +00:00
|
|
|
## Verification
|
2015-01-12 18:29:30 +00:00
|
|
|
|
2015-03-19 19:30:55 +00:00
|
|
|
When Git LFS clients issue a POST request to initiate an object upload, the
|
|
|
|
response can potentially return a "verify" link relation. If given, The Git LFS
|
|
|
|
API expects a POST to the href after a successful upload. Git LFS clients send:
|
2015-01-12 18:29:30 +00:00
|
|
|
|
|
|
|
* `oid` - The String OID of the Git Media object.
|
2015-02-13 18:53:35 +00:00
|
|
|
* `size` - The integer size of the Git Media object.
|
2015-01-12 18:29:30 +00:00
|
|
|
|
|
|
|
```
|
2015-03-19 19:30:55 +00:00
|
|
|
> POST https://git-lfs-server.com/callback
|
|
|
|
> Accept: application/vnd.git-lfs
|
|
|
|
> Content-Type: application/vnd.git-lfs+json
|
2015-01-12 18:29:30 +00:00
|
|
|
> Content-Length: 123
|
|
|
|
>
|
2015-02-13 18:53:35 +00:00
|
|
|
> {"oid": "{oid}", "size": 10000}
|
2015-01-14 00:02:15 +00:00
|
|
|
>
|
|
|
|
< HTTP/1.1 200 OK
|
2015-01-12 18:29:30 +00:00
|
|
|
```
|
2015-02-13 18:53:35 +00:00
|
|
|
|
|
|
|
A 200 response means that the object exists on the server.
|