github.com/x-oss-byte/git-lfs@v2.5.2+incompatible/docs/api/basic-transfers.md (about)

     1  # Basic Transfer API
     2  
     3  The Basic transfer API is a simple, generic API for directly uploading and
     4  downloading LFS objects. Git LFS servers can offload object storage to cloud
     5  services like S3, or implement this API natively.
     6  
     7  This is the original transfer adapter. All Git LFS clients and servers SHOULD
     8  support it, and default to it if the [Batch API](./batch.md) request or response
     9  do not specify a `transfer` property.
    10  
    11  ## Downloads
    12  
    13  Downloading an object requires a download `action` object in the Batch API
    14  response 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  
    38  The Basic transfer adapter will make a GET request on the `href`, expecting the
    39  raw 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  
    54  The client uploads objects through individual PUT requests. The URL and headers
    55  are 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  
    79  The Basic transfer adapter will make a PUT request on the `href`, sending the
    80  raw 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  
    95  The Batch API can optionally return a verify `action` object in addition to an
    96  upload `action` object. If given, The Batch API expects a POST to the href
    97  after 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  
   128  Git 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  
   144  A 200 response means that the object exists on the server.