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