diff --git a/docs/api/README.md b/docs/api/README.md index 141b3558..b076a23e 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -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": { diff --git a/docs/api/v1.3/http-v1.3-batch-request-schema.json b/docs/api/v1.3/http-v1.3-batch-request-schema.json new file mode 100644 index 00000000..25c2d756 --- /dev/null +++ b/docs/api/v1.3/http-v1.3-batch-request-schema.json @@ -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 +} diff --git a/docs/api/v1.3/http-v1.3-batch-response-schema.json b/docs/api/v1.3/http-v1.3-batch-response-schema.json new file mode 100644 index 00000000..65c59a6e --- /dev/null +++ b/docs/api/v1.3/http-v1.3-batch-response-schema.json @@ -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 +} diff --git a/docs/api/v1.3/http-v1.3-batch.md b/docs/api/v1.3/http-v1.3-batch.md new file mode 100644 index 00000000..7b5cb7d1 --- /dev/null +++ b/docs/api/v1.3/http-v1.3-batch.md @@ -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) diff --git a/docs/api/http-v1-batch-request-schema.json b/docs/api/v1/http-v1-batch-request-schema.json similarity index 100% rename from docs/api/http-v1-batch-request-schema.json rename to docs/api/v1/http-v1-batch-request-schema.json diff --git a/docs/api/http-v1-batch-response-schema.json b/docs/api/v1/http-v1-batch-response-schema.json similarity index 100% rename from docs/api/http-v1-batch-response-schema.json rename to docs/api/v1/http-v1-batch-response-schema.json diff --git a/docs/api/http-v1-batch.md b/docs/api/v1/http-v1-batch.md similarity index 98% rename from docs/api/http-v1-batch.md rename to docs/api/v1/http-v1-batch.md index a1c9f4f6..cae50c95 100644 --- a/docs/api/http-v1-batch.md +++ b/docs/api/v1/http-v1-batch.md @@ -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..access` config setting, where diff --git a/docs/api/http-v1-original.md b/docs/api/v1/http-v1-legacy.md similarity index 98% rename from docs/api/http-v1-original.md rename to docs/api/v1/http-v1-legacy.md index a7c147a8..a6f12bbc 100644 --- a/docs/api/http-v1-original.md +++ b/docs/api/v1/http-v1-legacy.md @@ -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