Update API docs for v1.3 transfer extensions
This commit is contained in:
parent
f2678fc830
commit
8dabcb25eb
@ -7,12 +7,12 @@ flow might look like:
|
||||
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.
|
||||
3. The client then transfers the objects through the transfer 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. By
|
||||
returning the proper info for the Git LFS client to use the transfer API. By
|
||||
default, API endpoint is based on the current Git remote. For example:
|
||||
|
||||
```
|
||||
@ -26,11 +26,17 @@ Git LFS endpoint: https://git-server.com/user/repo.git/info/lfs
|
||||
The [specification](/docs/spec.md) describes how clients can configure the Git LFS
|
||||
API endpoint manually.
|
||||
|
||||
The [original v1 API][v1] is used for Git LFS v0.5.x. An experimental [v1
|
||||
batch API][batch] is in the works for v0.6.x.
|
||||
The [legacy v1 API][legacy] was used for Git LFS v0.5.x. From 0.6.x the
|
||||
[batch API][batch] should always be used where available.
|
||||
|
||||
[legacy]: ./v1/http-v1-legacy.md
|
||||
[batch]: ./v1/http-v1-batch.md
|
||||
|
||||
From v1.3 there are [optional extensions to the batch API][batch v1.3] for more
|
||||
flexible transfers.
|
||||
|
||||
[batch v1.3]: ./v1.3/http-v1.3-batch.md
|
||||
|
||||
[v1]: ./http-v1-original.md
|
||||
[batch]: ./http-v1-batch.md
|
||||
|
||||
### Authentication
|
||||
|
||||
@ -81,43 +87,19 @@ HTTPS is strongly encouraged for all production Git LFS servers.
|
||||
If your Git LFS server authenticates with NTLM then you must provide your credentials to `git-credential`
|
||||
in the form `username:DOMAIN\user password:password`.
|
||||
|
||||
### Hypermedia
|
||||
## Transfer API
|
||||
|
||||
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.
|
||||
The transfer API is a generic API for directly uploading and downloading objects.
|
||||
Git LFS servers can offload object storage to cloud services like S3, or
|
||||
implemented natively in the Git LFS server. The only requirement is that
|
||||
hypermedia objects from the Git LFS API return the correct headers so clients
|
||||
can access the storage API properly.
|
||||
can access the transfer API properly.
|
||||
|
||||
As of v1.3 there can be multiple ways files can be uploaded or downloaded, see
|
||||
the [v1.3 API doc](v1.3/http-v1.3-batch.md) for details. The following section
|
||||
describes the basic transfer method which is the default.
|
||||
|
||||
### The basic transfer API
|
||||
|
||||
The client downloads objects through individual GET requests. The URL and any
|
||||
special headers are provided by a "download" hypermedia link:
|
||||
@ -125,7 +107,7 @@ special headers are provided by a "download" hypermedia link:
|
||||
```
|
||||
# the hypermedia object from the Git LFS API
|
||||
# {
|
||||
# "_links": {
|
||||
# "actions": {
|
||||
# "download": {
|
||||
# "href": "https://storage-server.com/OID",
|
||||
# "header": {
|
||||
@ -152,7 +134,7 @@ are provided by an "upload" hypermedia link:
|
||||
```
|
||||
# the hypermedia object from the Git LFS API
|
||||
# {
|
||||
# "_links": {
|
||||
# "actions": {
|
||||
# "upload": {
|
||||
# "href": "https://storage-server.com/OID",
|
||||
# "header": {
|
||||
|
34
docs/api/v1.3/http-v1.3-batch-request-schema.json
Normal file
34
docs/api/v1.3/http-v1.3-batch-request-schema.json
Normal file
@ -0,0 +1,34 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-04/schema",
|
||||
"title": "Git LFS HTTPS Batch API v1.3 Request",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"transfers": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
},
|
||||
"operation": {
|
||||
"type": "string"
|
||||
},
|
||||
"objects": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"oid": {
|
||||
"type": "string"
|
||||
},
|
||||
"size": {
|
||||
"type": "number"
|
||||
}
|
||||
},
|
||||
"required": ["oid", "size"],
|
||||
"additionalProperties": false
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": ["objects", "operation"],
|
||||
"additionalProperties": false
|
||||
}
|
80
docs/api/v1.3/http-v1.3-batch-response-schema.json
Normal file
80
docs/api/v1.3/http-v1.3-batch-response-schema.json
Normal file
@ -0,0 +1,80 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-04/schema",
|
||||
"title": "Git LFS HTTPS Batch API v1.3 Response",
|
||||
"type": "object",
|
||||
|
||||
"definitions": {
|
||||
"action": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"href": {
|
||||
"type": "string"
|
||||
},
|
||||
"header": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
},
|
||||
"expires_at": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": ["href"],
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
|
||||
"properties": {
|
||||
"transfer": {
|
||||
"type": "string"
|
||||
},
|
||||
"objects": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"oid": {
|
||||
"type": "string"
|
||||
},
|
||||
"size": {
|
||||
"type": "number"
|
||||
},
|
||||
"actions": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"download": { "$ref": "#/definitions/action" },
|
||||
"upload": { "$ref": "#/definitions/action" },
|
||||
"verify": { "$ref": "#/definitions/action" }
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"error": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "number"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": ["code", "message"],
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"required": ["oid", "size"],
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"request_id": {
|
||||
"type": "string"
|
||||
},
|
||||
"documentation_url": {
|
||||
"type": "string"
|
||||
},
|
||||
},
|
||||
"required": ["objects"],
|
||||
"additionalProperties": false
|
||||
}
|
98
docs/api/v1.3/http-v1.3-batch.md
Normal file
98
docs/api/v1.3/http-v1.3-batch.md
Normal file
@ -0,0 +1,98 @@
|
||||
# Git LFS v1.3 Batch API
|
||||
|
||||
The Git LFS Batch API extends the [batch v1 API](../v1/http-v1-batch.md), adding
|
||||
optional fields to the request and response to negotiate transfer methods.
|
||||
|
||||
Only the differences from the v1 API will be listed here, everything else is
|
||||
unchanged.
|
||||
|
||||
## POST /objects/batch
|
||||
### Request changes
|
||||
|
||||
The v1.3 request adds an additional optional top-level field, `transfers`,
|
||||
which is an array of strings naming the transfer methods this client supports.
|
||||
The transfer methods are in decreasing order of preference.
|
||||
|
||||
The default transfer method which simply uploads and downloads using simple HTTP
|
||||
`PUT` and `GET`, named "basic", is always supported and is implied.
|
||||
|
||||
Example request:
|
||||
|
||||
```
|
||||
> 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)
|
||||
>
|
||||
> {
|
||||
> "operation": "upload",
|
||||
> "transfers": [ "tus.io", "basic" ]
|
||||
> "objects": [
|
||||
> {
|
||||
> "oid": "1111111",
|
||||
> "size": 123
|
||||
> }
|
||||
> ]
|
||||
> }
|
||||
>
|
||||
```
|
||||
|
||||
In the example above `"basic"` is included for illustration but is actually
|
||||
unnecessary since it is always the fallback. The client is indicating that it is
|
||||
able to upload using the resumable `"tus.io"` method, should the server support
|
||||
that. The server may include a chosen method in the response, which must be
|
||||
one of those listed, or `"basic"`.
|
||||
|
||||
### Response changes
|
||||
|
||||
If the server understands the new optional `transfers` field in the request, it
|
||||
should determine which of the named transfer methods it also supports, and
|
||||
include the chosen one in the response in the new `transfer` field. If only
|
||||
`"basic"` is supported, the field is optional since that is the default.
|
||||
|
||||
If the server supports more than one of the named transfer methods, it should
|
||||
pick the first one it supports, since the client will list them in order of
|
||||
preference.
|
||||
|
||||
Example response to the previous request if the server also supports `tus.io`:
|
||||
|
||||
```
|
||||
< HTTP/1.1 200 Ok
|
||||
< Content-Type: application/vnd.git-lfs+json
|
||||
<
|
||||
< {
|
||||
< "transfer": "tus.io",
|
||||
< "objects": [
|
||||
< {
|
||||
< "oid": "1111111",
|
||||
< "size": 123,
|
||||
< "actions": {
|
||||
< "upload": {
|
||||
< "href": "https://some-tus-io-upload.com",
|
||||
< "header": {
|
||||
< "Key": "value"
|
||||
< }
|
||||
< },
|
||||
< "verify": {
|
||||
< "href": "https://some-callback.com",
|
||||
< "header": {
|
||||
< "Key": "value"
|
||||
< }
|
||||
< }
|
||||
< }
|
||||
> }
|
||||
< ]
|
||||
< }
|
||||
```
|
||||
|
||||
Apart from naming the chosen transfer method in `transfer`, the server should
|
||||
also return upload / download links in the `href` field which are compatible
|
||||
with the method chosen. If the server supports more than one method (and it's
|
||||
advisable that the server implement at least `"basic` in all cases in addition
|
||||
to more sophisticated methods, to support older clients), the `href` is likely
|
||||
to be different for each.
|
||||
|
||||
## Updated schemas
|
||||
|
||||
* [Batch request](./http-v1.3-batch-request-schema.json)
|
||||
* [Batch response](./http-v1.3-batch-response-schema.json)
|
@ -1,12 +1,12 @@
|
||||
# Git LFS v1 Batch API
|
||||
|
||||
The Git LFS Batch API works like the [original v1 API][v1], but uses a single
|
||||
The Git LFS Batch API works like the [legacy v1 API][v1], but uses a single
|
||||
endpoint that accepts multiple OIDs. All requests should have the following:
|
||||
|
||||
Accept: application/vnd.git-lfs+json
|
||||
Content-Type: application/vnd.git-lfs+json
|
||||
|
||||
[v1]: ./http-v1-original.md
|
||||
[v1]: ./http-v1-legacy.md
|
||||
|
||||
This is a newer API introduced in Git LFS v0.5.2, and made the default in
|
||||
Git LFS v0.6.0. The client automatically detects if the server does not
|
||||
@ -21,7 +21,7 @@ manually through the Git config:
|
||||
|
||||
## Authentication
|
||||
|
||||
The Batch API authenticates the same as the original v1 API with one exception:
|
||||
The Batch API authenticates the same as the legacy v1 API with one exception:
|
||||
The client will attempt to make requests without any authentication. This
|
||||
slight change allows anonymous access to public Git LFS objects. The client
|
||||
stores the result of this in the `lfs.<url>.access` config setting, where <url>
|
@ -1,6 +1,6 @@
|
||||
# Git LFS v1 Original API
|
||||
# Git LFS v1 Legacy API
|
||||
|
||||
This describes the original API for Git LFS v0.5.x. It's already deprecated by
|
||||
This describes the legacy 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
|
Loading…
Reference in New Issue
Block a user