199 lines
6.4 KiB
Markdown
199 lines
6.4 KiB
Markdown
# Git LFS v1 Original API
|
||
|
||
This describes the original API for Git LFS v0.5.x. It's already deprecated by
|
||
the [batch API][batch]. All requests should have:
|
||
|
||
Accept: application/vnd.git-lfs+json
|
||
Content-Type: application/vnd.git-lfs+json
|
||
|
||
[batch]: ./http-v1-batch.md
|
||
|
||
## 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 must follow hypermedia
|
||
links to actually upload the content.
|
||
* 301 - A permanent redirect. Only supported for GET/HEAD requests.
|
||
* 302 - A temporary redirect. Only supported for GET/HEAD requests.
|
||
* 303 - A temporary redirect. Only supported for GET/HEAD requests.
|
||
* 307 - A temporary redirect. Keeps the original request method intact.
|
||
* 400 - General error with the client's request. Invalid JSON formatting, for
|
||
example.
|
||
* 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
|
||
the server implementation.
|
||
|
||
* 406 - The Accept header needs to be `application/vnd.git-lfs+json`.
|
||
* 410 - The requested object used to exist, but was deleted. The message should
|
||
state why (user initiated, legal issues, etc).
|
||
* 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.
|
||
|
||
If the server returns a JSON error object, the client can display this message
|
||
to users.
|
||
|
||
```
|
||
> GET https://git-lfs-server.com/objects/{OID} HTTP/1.1
|
||
> Accept: application/vnd.git-lfs+json
|
||
>
|
||
< HTTP/1.1 200 OK
|
||
< Content-Type: application/vnd.git-lfs+json
|
||
<
|
||
< {
|
||
< "message": "Bad credentials",
|
||
< "documentation_url": "https://git-lfs-server.com/docs/errors",
|
||
< "request_id": "123"
|
||
< }
|
||
```
|
||
|
||
The `documentation_url` and `request_id` properties are optional. If given,
|
||
they are displayed to the user.
|
||
|
||
## Redirections
|
||
|
||
The Git LFS client follows redirections on the core Git LFS API methods only.
|
||
Any of the hypermedia hrefs that are returned must be for the current location.
|
||
The client will pass all of the original request headers to the redirected
|
||
request, only changing the URL based on the redirect location. The only
|
||
exception is the Authorization header, which is only passed through if the
|
||
original request and the new location have a matching URL scheme, host, and
|
||
port.
|
||
|
||
The client will automatically follow redirections for GET or HEAD requests on
|
||
a 301, 302, 303, or 307 HTTP status. It only automatically follows redirections
|
||
for other HTTP verbs on a 307 HTTP status.
|
||
|
||
Note: the 308 HTTP status is not official, and has conflicting proposals for its
|
||
intended use. It is not supported as a redirection.
|
||
|
||
## GET /objects/{oid}
|
||
|
||
This gets the object's meta data. The OID is the value from the object pointer.
|
||
|
||
```
|
||
> GET https://git-lfs-server.com/objects/{OID} HTTP/1.1
|
||
> Accept: application/vnd.git-lfs+json
|
||
> Authorization: Basic ... (if authentication is needed)
|
||
>
|
||
< HTTP/1.1 200 OK
|
||
< Content-Type: application/vnd.git-lfs+json
|
||
<
|
||
< {
|
||
< "oid": "the-sha-256-signature",
|
||
< "size": 123456,
|
||
< "_links": {
|
||
< "self": {
|
||
< "href": "https://git-lfs-server.com/objects/OID",
|
||
< },
|
||
< "download": {
|
||
< "href": "https://some-download.com",
|
||
< "header": {
|
||
< "Key": "value"
|
||
< }
|
||
< }
|
||
< }
|
||
< }
|
||
```
|
||
|
||
The `oid` and `size` properties are required. A hypermedia `_links` section is
|
||
included with a `download` link relation. Clients can follow this link to
|
||
access the object content. See the "Hypermedia" section above for more.
|
||
|
||
Here's a sample response for a request with an authorization error:
|
||
|
||
```
|
||
> GET https://git-lfs-server.com/objects/{OID} HTTP/1.1
|
||
> Accept: application/vnd.git-lfs+json
|
||
> Authorization: Basic ... (if authentication is needed)
|
||
>
|
||
< HTTP/1.1 404 Not found
|
||
< Content-Type: application/vnd.git-lfs+json
|
||
<
|
||
< {
|
||
< "message": "Not found"
|
||
< }
|
||
```
|
||
|
||
### Responses
|
||
|
||
* 200 - The object exists and the user has access to download it.
|
||
* 401 - The authentication credentials are incorrect.
|
||
* 404 - The user does not have access to the object, or it does not exist.
|
||
* 410 - The object used to exist, but was deleted. The message should state why
|
||
(user initiated, legal issues, etc).
|
||
|
||
## POST /objects
|
||
|
||
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-lfs-server.com/objects HTTP/1.1
|
||
> Accept: application/vnd.git-lfs+json
|
||
> Content-Type: application/vnd.git-lfs+json
|
||
> Authorization: Basic ... (if authentication is needed)
|
||
>
|
||
> {
|
||
> "oid": "1111111",
|
||
> "size": 123
|
||
> }
|
||
>
|
||
< HTTP/1.1 202 Accepted
|
||
< Content-Type: application/vnd.git-lfs+json
|
||
<
|
||
< {
|
||
< "_links": {
|
||
< "upload": {
|
||
< "href": "https://some-upload.com",
|
||
< "header": {
|
||
< "Key": "value"
|
||
< }
|
||
< },
|
||
< "verify": {
|
||
< "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.
|
||
|
||
* `upload` - This relation describes how to upload the object. Expect this with
|
||
a 202 status.
|
||
* `verify` - The server can specify a URL for the client to hit after
|
||
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.
|
||
|
||
### Responses
|
||
|
||
* 200 - The object already exists. Don't bother re-uploading.
|
||
* 202 - The object is ready to be uploaded. Follow the "upload" and optional
|
||
"verify" links.
|
||
* 401 - The authentication credentials are incorrect.
|
||
* 403 - The user has **read**, but not **write** access.
|
||
* 404 - The repository does not exist for the user.
|