add the api readme
This commit is contained in:
Rick Olson
parent
9837c6df8a
commit
99ce648feb
358
docs/api.md
358
docs/api.md
@ -1,358 +0,0 @@
|
||||
# Git LFS API
|
||||
|
||||
The server implements a simple API for uploading and downloading binary content.
|
||||
Git repositories that use Git LFS will specify a URI endpoint. See the
|
||||
[specification](spec.md) for how Git LFS 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 LFS server.
|
||||
|
||||
API requests require an Accept header of `application/vnd.git-lfs+json`. The
|
||||
upload and verify requests need a `application/vnd.git-lfs+json` Content-Type
|
||||
too.
|
||||
|
||||
## Authentication
|
||||
|
||||
The Git LFS API uses [git credentials](http://git-scm.com/docs/gitcredentials) to
|
||||
access the API username and password. If the Git LFS domain matches the Git
|
||||
remote's, Git LFS will not prompt you again to enter the password.
|
||||
|
||||
If the Git remote is using SSH, Git LFS will execute the `git-lfs-authenticate`
|
||||
command. It passes the SSH path, the Git LFS operation (upload or download),
|
||||
and the object OID as arguments. A successful result outputs a JSON link object
|
||||
to STDOUT. This is applied to any Git LFS API request before git credentials
|
||||
are accessed.
|
||||
|
||||
```
|
||||
# remote: git@github.com:user/repo.git
|
||||
$ ssh git@github.com git-lfs-authenticate user/repo.git download {oid}
|
||||
{
|
||||
"header": {
|
||||
"Authorization": "Basic ..."
|
||||
}
|
||||
// OPTIONAL key only needed if the Git LFS server is not hosted at the default
|
||||
// URL from the Git remote:
|
||||
// https://github.com/user/repo.git/info/lfs
|
||||
"href": "https://other-server.com/user/repo",
|
||||
}
|
||||
```
|
||||
|
||||
If Git LFS detects a non-zero exit status, it displays the command's STDERR:
|
||||
|
||||
```
|
||||
$ ssh git@github.com git-lfs-authenticate user/repo.git wat {oid}
|
||||
Invalid LFS operation: "wat"
|
||||
```
|
||||
|
||||
NOTE: The Git LFS client currently does not cache the headers from the SSH
|
||||
command. This is being considered for a future release.
|
||||
|
||||
## 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.
|
||||
|
||||
## Hypermedia
|
||||
|
||||
The Git LFS API uses hypermedia hints to instruct the client what to do next.
|
||||
These links are included in a `_links` property. Possible relations for objects
|
||||
include:
|
||||
|
||||
* `self` - This points to the object's canonical API URL.
|
||||
* `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.
|
||||
|
||||
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
|
||||
store that the Git LFS API is using.
|
||||
|
||||
The Git LFS client will automatically send the same credentials to the followed
|
||||
link relation as Basic Authentication IF:
|
||||
|
||||
* The url scheme, host, and port all match the Git LFS API endpoint's.
|
||||
* The link relation does not specify an Authorization header.
|
||||
|
||||
If the host name is different, the Git LFS API needs to send enough information
|
||||
through the href query or header values to authenticate the request.
|
||||
|
||||
The Git LFS client expects a 200 or 201 response from these hypermedia requests.
|
||||
Any other response code is treated as an error.
|
||||
|
||||
## 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.
|
||||
|
||||
## POST /objects/batch
|
||||
|
||||
This request retrieves the metadata for a batch of objects, given a JSON body
|
||||
containing an object with an array of objects with the oid and size of each object.
|
||||
|
||||
NOTE: This is an experimental API that is subject to change. It will ship disabled
|
||||
by default in Git LFS v0.5.2. You can enable it if your Git LFS server supports it
|
||||
with `git config lfs.batch true`.
|
||||
|
||||
```
|
||||
> POST https://git-lfs-server.com/objects/batch HTTP/1.1
|
||||
> Accept: application/vnd.git-lfs+json
|
||||
> Content-Type: application/vnd.git-lfs+json
|
||||
> Authorization: Basic ... (if authentication is needed)
|
||||
>
|
||||
> {
|
||||
> "objects": [
|
||||
> {
|
||||
> "oid": "1111111",
|
||||
> "size": 123
|
||||
> }
|
||||
> ]
|
||||
> }
|
||||
>
|
||||
< HTTP/1.1 200 Accepted
|
||||
< Content-Type: application/vnd.git-lfs+json
|
||||
<
|
||||
< {
|
||||
< "objects": [
|
||||
< {
|
||||
< "oid": "1111111",
|
||||
< "_links": {
|
||||
< "upload": {
|
||||
< "href": "https://some-upload.com",
|
||||
< "header": {
|
||||
< "Key": "value"
|
||||
< }
|
||||
< },
|
||||
< "verify": {
|
||||
< "href": "https://some-callback.com",
|
||||
< "header": {
|
||||
< "Key": "value"
|
||||
< }
|
||||
< }
|
||||
< }
|
||||
> }
|
||||
< ]
|
||||
< }
|
||||
```
|
||||
|
||||
The response will be an object containing an array of objects with 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
|
||||
when the object has not been previously uploaded.
|
||||
* `verify` - The server can specify a URL for the client to hit after
|
||||
successfully uploading an object. This is an optional relation for the case that
|
||||
the server has not verified the object.
|
||||
* `download` - This relation describes how to download the object content. This
|
||||
only appears if an object has been previously uploaded.
|
||||
|
||||
### Responses
|
||||
|
||||
* 200 - OK
|
||||
* 401 - The authentication credentials are incorrect.
|
||||
* 403 - The user has **read**, but not **write** access.
|
||||
* 404 - The repository does not exist for the user.
|
||||
|
||||
## Verification
|
||||
|
||||
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:
|
||||
|
||||
* `oid` - The String OID of the Git LFS object.
|
||||
* `size` - The integer size of the Git LFS object, in bytes.
|
||||
|
||||
```
|
||||
> POST https://git-lfs-server.com/callback
|
||||
> Accept: application/vnd.git-lfs+json
|
||||
> Content-Type: application/vnd.git-lfs+json
|
||||
> Content-Length: 123
|
||||
>
|
||||
> {"oid": "{oid}", "size": 10000}
|
||||
>
|
||||
< HTTP/1.1 200 OK
|
||||
```
|
||||
|
||||
A 200 response means that the object exists on the server.
|
||||
188
docs/api/README.md
Normal file
188
docs/api/README.md
Normal file
@ -0,0 +1,188 @@
|
||||
# Git LFS API
|
||||
|
||||
The Git LFS client talks to an API to upload and download objects. A typical
|
||||
flow might look like:
|
||||
|
||||
1. The user runs a command to download (`git lfs fetch`) or upload (`git lfs
|
||||
push`) objects.
|
||||
2. The client contacts the Git LFS API to get information about transferring
|
||||
the objects.
|
||||
3. The client then transfers the objects through the storage API.
|
||||
|
||||
## HTTP API
|
||||
|
||||
The Git LFS HTTP API is responsible for authenticating the user requests, and
|
||||
returning the proper info for the Git LFS client to use the storage API.
|
||||
|
||||
The [specification](spec.md) describes how clients can configure the Git LFS
|
||||
API endpoint. By default, it's based on the current Git remote. For example:
|
||||
|
||||
```
|
||||
Git remote: https://git-server.com/user/repo.git
|
||||
Git LFS endpoint: https://git-server.com/user/repo.git/info/lfs
|
||||
|
||||
Git remote: git@git-server.com:user/repo.git
|
||||
Git LFS endpoint: https://git-server.com/user/repo.git/info/lfs
|
||||
```
|
||||
|
||||
As of Git LFS v0.5.2, the [original v1 API][v1] is used. An experimental
|
||||
[v1 batch API][batch] is in the works for v0.6.x+.
|
||||
|
||||
[v1]: ./http-v1-original.md
|
||||
[batch]: ./http-v1-batch.md
|
||||
|
||||
### Authentication
|
||||
|
||||
HTTP Basic Authentication is used to send authentication. The credentials can
|
||||
come from the following places:
|
||||
|
||||
1. Specified in the URL: `https://user:password@git-server.com/user/repo.git/info/lfs`.
|
||||
This is not recommended because it relies on the credentials living in your
|
||||
local git config.
|
||||
2. `git-credential` will either retrieve the stored credentials for your Git
|
||||
host, or ask you to provide them. Successful requests will store the credentials
|
||||
for later if you have a [good git credential cacher](https://help.github.com/articles/caching-your-github-password-in-git/).
|
||||
3. SSH
|
||||
|
||||
If the Git remote is using SSH, Git LFS will execute the `git-lfs-authenticate`
|
||||
command. It passes the SSH path, the Git LFS operation (upload or download),
|
||||
and the object OID as arguments. A successful result outputs a JSON link object
|
||||
to STDOUT. This is applied to any Git LFS API request before git credentials
|
||||
are accessed.
|
||||
|
||||
```
|
||||
# remote: git@github.com:user/repo.git
|
||||
$ ssh git@github.com git-lfs-authenticate user/repo.git download {oid}
|
||||
{
|
||||
"header": {
|
||||
"Authorization": "Basic ..."
|
||||
}
|
||||
// OPTIONAL key only needed if the Git LFS server is not hosted at the default
|
||||
// URL from the Git remote:
|
||||
// https://github.com/user/repo.git/info/lfs
|
||||
"href": "https://other-server.com/user/repo",
|
||||
}
|
||||
```
|
||||
|
||||
If Git LFS detects a non-zero exit status, it displays the command's STDERR:
|
||||
|
||||
```
|
||||
$ ssh git@github.com git-lfs-authenticate user/repo.git wat {oid}
|
||||
Invalid LFS operation: "wat"
|
||||
```
|
||||
|
||||
HTTPS is strongly encouraged for all production Git LFS servers.
|
||||
|
||||
### Hypermedia
|
||||
|
||||
The Git LFS API uses hypermedia hints to instruct the client what to do next.
|
||||
These links are included in a `_links` property. Possible relations for objects
|
||||
include:
|
||||
|
||||
* `self` - This points to the object's canonical API URL.
|
||||
* `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.
|
||||
|
||||
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
|
||||
store that the Git LFS API is using.
|
||||
|
||||
The Git LFS client will automatically send the same credentials to the followed
|
||||
link relation as Basic Authentication IF:
|
||||
|
||||
* The url scheme, host, and port all match the Git LFS API endpoint's.
|
||||
* The link relation does not specify an Authorization header.
|
||||
|
||||
If the host name is different, the Git LFS API needs to send enough information
|
||||
through the href query or header values to authenticate the request.
|
||||
|
||||
The Git LFS client expects a 200 or 201 response from these hypermedia requests.
|
||||
Any other response code is treated as an error.
|
||||
|
||||
## Storage API
|
||||
|
||||
The Storage API is a generic API for directly uploading and downloading objects.
|
||||
Git LFS servers can offload object storage to cloud services like S3, or
|
||||
implement the simple actions natively. The only requirement is that hypermedia
|
||||
objects from the Git LFS API return enough information for Git LFS clients to
|
||||
upload and download the objects.
|
||||
|
||||
The client downloads objects through individual GET requests. The URL and any
|
||||
special headers are provided by a "download" hypermedia link:
|
||||
|
||||
```
|
||||
# the hypermedia object from the Git LFS API
|
||||
# {
|
||||
# "_links": {
|
||||
# "download": {
|
||||
# "href": "https://storage-server.com/OID",
|
||||
# "header": {
|
||||
# "Authorization": "Basic ...",
|
||||
# }
|
||||
# }
|
||||
# }
|
||||
# }
|
||||
|
||||
# This request expects the raw object contents in the response.
|
||||
> GET https://storage-server.com/OID
|
||||
> Authorization: Basic ...
|
||||
<
|
||||
< HTTP/1.1 200 OK
|
||||
< Content-Type: application/octet-stream
|
||||
< Content-Length: 123
|
||||
<
|
||||
< {contents}
|
||||
```
|
||||
|
||||
The client uploads objects through individual PUT requests. The URL and headers
|
||||
are provided by an "upload" hypermedia link:
|
||||
|
||||
```
|
||||
# the hypermedia object from the Git LFS API
|
||||
# {
|
||||
# "_links": {
|
||||
# "upload": {
|
||||
# "href": "https://storage-server.com/OID",
|
||||
# "header": {
|
||||
# "Authorization": "Basic ...",
|
||||
# }
|
||||
# }
|
||||
# }
|
||||
# }
|
||||
|
||||
# This sends the raw object contents as the request body.
|
||||
> PUT https://storage-server.com/OID
|
||||
> Authorization: Basic ...
|
||||
> Content-Type: application/octet-stream
|
||||
> Content-Length: 123
|
||||
>
|
||||
> {contents}
|
||||
>
|
||||
< HTTP/1.1 200 OK
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
The Git LFS API can optionally return a "verify" hypermedia link in addition to
|
||||
an "upload" link. If given, The Git LFS API expects a POST to the href after a
|
||||
successful upload. Git LFS clients send:
|
||||
|
||||
* `oid` - The String OID of the Git LFS object.
|
||||
* `size` - The integer size of the Git LFS object, in bytes.
|
||||
|
||||
```
|
||||
> POST https://git-lfs-server.com/callback
|
||||
> Accept: application/vnd.git-lfs+json
|
||||
> Content-Type: application/vnd.git-lfs+json
|
||||
> Content-Length: 123
|
||||
>
|
||||
> {"oid": "{oid}", "size": 10000}
|
||||
>
|
||||
< HTTP/1.1 200 OK
|
||||
```
|
||||
|
||||
A 200 response means that the object exists on the server.
|
||||
@ -87,36 +87,6 @@ to users.
|
||||
The `documentation_url` and `request_id` properties are optional. If given,
|
||||
they are displayed to the user.
|
||||
|
||||
## Hypermedia
|
||||
|
||||
The Git LFS API uses hypermedia hints to instruct the client what to do next.
|
||||
These links are included in a `_links` property. Possible relations for objects
|
||||
include:
|
||||
|
||||
* `self` - This points to the object's canonical API URL.
|
||||
* `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.
|
||||
|
||||
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
|
||||
store that the Git LFS API is using.
|
||||
|
||||
The Git LFS client will automatically send the same credentials to the followed
|
||||
link relation as Basic Authentication IF:
|
||||
|
||||
* The url scheme, host, and port all match the Git LFS API endpoint's.
|
||||
* The link relation does not specify an Authorization header.
|
||||
|
||||
If the host name is different, the Git LFS API needs to send enough information
|
||||
through the href query or header values to authenticate the request.
|
||||
|
||||
The Git LFS client expects a 200 or 201 response from these hypermedia requests.
|
||||
Any other response code is treated as an error.
|
||||
|
||||
## POST /objects/batch
|
||||
|
||||
This request retrieves the metadata for a batch of objects, given a JSON body
|
||||
@ -198,25 +168,3 @@ only appears if an object has been previously uploaded.
|
||||
* 401 - The authentication credentials are needed, but were not sent.
|
||||
* 403 - The user has **read**, but not **write** access.
|
||||
* 404 - The repository does not exist for the user.
|
||||
|
||||
## Verification
|
||||
|
||||
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:
|
||||
|
||||
* `oid` - The String OID of the Git LFS object.
|
||||
* `size` - The integer size of the Git LFS object, in bytes.
|
||||
|
||||
```
|
||||
> POST https://git-lfs-server.com/callback
|
||||
> Accept: application/vnd.git-lfs+json
|
||||
> Content-Type: application/vnd.git-lfs+json
|
||||
> Content-Length: 123
|
||||
>
|
||||
> {"oid": "{oid}", "size": 10000}
|
||||
>
|
||||
< HTTP/1.1 200 OK
|
||||
```
|
||||
|
||||
A 200 response means that the object exists on the server.
|
||||
|
||||
@ -84,36 +84,6 @@ 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.
|
||||
|
||||
## Hypermedia
|
||||
|
||||
The Git LFS API uses hypermedia hints to instruct the client what to do next.
|
||||
These links are included in a `_links` property. Possible relations for objects
|
||||
include:
|
||||
|
||||
* `self` - This points to the object's canonical API URL.
|
||||
* `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.
|
||||
|
||||
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
|
||||
store that the Git LFS API is using.
|
||||
|
||||
The Git LFS client will automatically send the same credentials to the followed
|
||||
link relation as Basic Authentication IF:
|
||||
|
||||
* The url scheme, host, and port all match the Git LFS API endpoint's.
|
||||
* The link relation does not specify an Authorization header.
|
||||
|
||||
If the host name is different, the Git LFS API needs to send enough information
|
||||
through the href query or header values to authenticate the request.
|
||||
|
||||
The Git LFS client expects a 200 or 201 response from these hypermedia requests.
|
||||
Any other response code is treated as an error.
|
||||
|
||||
## GET /objects/{oid}
|
||||
|
||||
This gets the object's meta data. The OID is the value from the object pointer.
|
||||
@ -226,25 +196,3 @@ only appears on a 200 status.
|
||||
* 401 - The authentication credentials are incorrect.
|
||||
* 403 - The user has **read**, but not **write** access.
|
||||
* 404 - The repository does not exist for the user.
|
||||
|
||||
## Verification
|
||||
|
||||
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:
|
||||
|
||||
* `oid` - The String OID of the Git LFS object.
|
||||
* `size` - The integer size of the Git LFS object, in bytes.
|
||||
|
||||
```
|
||||
> POST https://git-lfs-server.com/callback
|
||||
> Accept: application/vnd.git-lfs+json
|
||||
> Content-Type: application/vnd.git-lfs+json
|
||||
> Content-Length: 123
|
||||
>
|
||||
> {"oid": "{oid}", "size": 10000}
|
||||
>
|
||||
< HTTP/1.1 200 OK
|
||||
```
|
||||
|
||||
A 200 response means that the object exists on the server.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user