1# Basic Transfer API
2
3The Basic transfer API is a simple, generic API for directly uploading and
4downloading LFS objects. Git LFS servers can offload object storage to cloud
5services like S3, or implement this API natively.
6
7This is the original transfer adapter. All Git LFS clients and servers SHOULD
8support it, and default to it if the [Batch API](./batch.md) request or response
9do not specify a `transfer` property.
10
11## Downloads
12
13Downloading an object requires a download `action` object in the Batch API
14response that looks like this:
15
16```json
17{
18  "transfer": "basic",
19  "objects": [
20    {
21      "oid": "1111111",
22      "size": 123,
23      "authenticated": true,
24      "actions": {
25        "download": {
26          "href": "https://some-download.com/1111111",
27          "header": {
28            "Authorization": "Basic ..."
29          },
30          "expires_in": 86400,
31        }
32      }
33    }
34  ]
35}
36```
37
38The Basic transfer adapter will make a GET request on the `href`, expecting the
39raw bytes returned in the HTTP response.
40
41```
42> GET https://some-download.com/1111111
43> Authorization: Basic ...
44<
45< HTTP/1.1 200 OK
46< Content-Type: application/octet-stream
47< Content-Length: 123
48<
49< {contents}
50```
51
52## Uploads
53
54The client uploads objects through individual PUT requests. The URL and headers
55are provided by an upload `action` object.
56
57```json
58{
59  "transfer": "basic",
60  "objects": [
61    {
62      "oid": "1111111",
63      "size": 123,
64      "authenticated": true,
65      "actions": {
66        "upload": {
67          "href": "https://some-upload.com/1111111",
68          "header": {
69            "Authorization": "Basic ..."
70          },
71          "expires_in": 86400
72        }
73      }
74    }
75  ]
76}
77```
78
79The Basic transfer adapter will make a PUT request on the `href`, sending the
80raw bytes returned in the HTTP request.
81
82```
83> PUT https://some-upload.com/1111111
84> Authorization: Basic ...
85> Content-Type: application/octet-stream
86> Content-Length: 123
87>
88> {contents}
89>
90< HTTP/1.1 200 OK
91```
92
93## Verification
94
95The Batch API can optionally return a verify `action` object in addition to an
96upload `action` object. If given, The Batch API expects a POST to the href
97after a successful upload.
98
99```json
100{
101  "transfer": "basic",
102  "objects": [
103    {
104      "oid": "1111111",
105      "size": 123,
106      "authenticated": true,
107      "actions": {
108        "upload": {
109          "href": "https://some-upload.com/1111111",
110          "header": {
111            "Authorization": "Basic ..."
112          },
113          "expires_in": 86400
114        },
115        "verify": {
116          "href": "https://some-verify-callback.com",
117          "header": {
118            "Authorization": "Basic ..."
119          },
120          "expires_in": 86400
121        }
122      }
123    }
124  ]
125}
126```
127
128Git LFS clients send:
129
130* `oid` - The String OID of the Git LFS object.
131* `size` - The integer size of the Git LFS object, in bytes.
132
133```
134> POST https://some-verify-callback.com
135> Accept: application/vnd.git-lfs+json
136> Content-Type: application/vnd.git-lfs+json
137> Content-Length: 123
138>
139> {"oid": "{oid}", "size": 10000}
140>
141< HTTP/1.1 200 OK
142```
143
144A 200 response means that the object exists on the server.
145