github.com/git-lfs/git-lfs@v2.5.2+incompatible/docs/proposals/locking_api.md (about)

     1  # Locking API proposal
     2  
     3  ## POST /locks
     4  
     5  | Method  | Accept                         | Content-Type                   | Authorization |
     6  |---------|--------------------------------|--------------------------------|---------------|
     7  | `POST`  | `application/vnd.git-lfs+json` | `application/vnd.git-lfs+json` | Basic         |
     8  
     9  ### Request
    10  
    11  ```
    12  > GET https://git-lfs-server.com/locks
    13  > Accept: application/vnd.git-lfs+json
    14  > Authorization: Basic
    15  > Content-Type: application/vnd.git-lfs+json
    16  >
    17  > {
    18  >   path: "/path/to/file",
    19  >   remote: "origin",
    20  >   latest_remote_commit: "d3adbeef",
    21  >   committer: {
    22  >     name: "Jane Doe",
    23  >     email: "jane@example.com"
    24  >   }
    25  > }
    26  ```
    27  
    28  ### Response
    29  
    30  * **Successful response**
    31  ```
    32  < HTTP/1.1 201 Created
    33  < Content-Type: application/vnd.git-lfs+json
    34  <
    35  < {
    36  <   lock: {
    37  <     id: "some-uuid",
    38  <     path: "/path/to/file",
    39  <     committer: {
    40  <       name: "Jane Doe",
    41  <       email: "jane@example.com"
    42  <     },
    43  <     commit_sha: "d3adbeef",
    44  <     locked_at: "2016-05-17T15:49:06+00:00"
    45  <   }
    46  < }
    47  ```
    48  
    49  * **Bad request: minimum commit not met**
    50  ```
    51  < HTTP/1.1 400 Bad request
    52  < Content-Type: application/vnd.git-lfs+json
    53  <
    54  < {
    55  <   "commit_needed": "other_sha"
    56  < }
    57  ```
    58  
    59  * **Bad request: lock already present**
    60  ```
    61  < HTTP/1.1 409 Conflict
    62  < Content-Type: application/vnd.git-lfs+json
    63  <
    64  < {
    65  <   lock: {
    66  <     /* the previously created lock */
    67  <   },
    68  <   error: "already created lock"
    69  < }
    70  ```
    71  
    72  * **Bad repsonse: server error**
    73  ```
    74  < HTTP/1.1 500 Internal server error
    75  < Content-Type: application/vnd.git-lfs+json
    76  <
    77  < {
    78  <   error: "unable to create lock"
    79  < }
    80  ```
    81  
    82  ## POST /locks/:id/unlock
    83  
    84  | Method  | Accept                         | Content-Type | Authorization |
    85  |---------|--------------------------------|--------------|---------------|
    86  | `POST`  | `application/vnd.git-lfs+json` | None         | Basic         |
    87  
    88  ### Request
    89  
    90  ```
    91  > POST https://git-lfs-server.com/locks/:id/unlock
    92  > Accept: application/vnd.git-lfs+json
    93  > Authorization: Basic
    94  ```
    95  
    96  ### Repsonse
    97  
    98  * **Success: unlocked**
    99  ```
   100  < HTTP/1.1 200 Ok
   101  < Content-Type: application/vnd.git-lfs+json
   102  <
   103  < {
   104  <   lock: {
   105  <     id: "some-uuid",
   106  <     path: "/path/to/file",
   107  <     committer: {
   108  <       name: "Jane Doe",
   109  <       email: "jane@example.com"
   110  <     },
   111  <     commit_sha: "d3adbeef",
   112  <     locked_at: "2016-05-17T15:49:06+00:00",
   113  <     unlocked_at: "2016-05-17T15:49:06+00:00"
   114  <   }
   115  < }
   116  }
   117  ```
   118  
   119  * **Bad response: server error**
   120  ```
   121  < HTTP/1.1 500 Internal error
   122  < Content-Type: application/vnd.git-lfs+json
   123  <
   124  < {
   125  <   error: "git-lfs/git-lfs: internal server error"
   126  < }
   127  ```
   128  
   129  ## GET /locks
   130  
   131  | Method | Accept                        | Content-Type | Authorization |
   132  |--------|-------------------------------|--------------|---------------|
   133  | `GET`  | `application/vnd.git-lfs+json | None         | Basic         |
   134  
   135  ### Request
   136  
   137  ```
   138  > GET https://git-lfs-server.com/locks?filters...&cursor=&limit=
   139  > Accept: application/vnd.git-lfs+json
   140  > Authorization: Basic
   141  ```
   142  
   143  ### Response
   144  
   145  * **Success: locks found**
   146  
   147  Note: no matching locks yields a payload of `locks: []`, and a status of 200.
   148  
   149  ```
   150  < HTTP/1.1 200 Ok
   151  < Content-Type: application/vnd.git-lfs+json
   152  <
   153  < {
   154  <   locks: [
   155  <     {
   156  <       id: "some-uuid",
   157  <       path: "/path/to/file",
   158  <       committer": {
   159  <         name: "Jane Doe",
   160  <         email: "jane@example.com"
   161  <       },
   162  <       commit_sha: "1ec245f",
   163  <       locked_at: "2016-05-17T15:49:06+00:00"
   164  <     }
   165  <   ],
   166  <   next_cursor: "optional-next-id",
   167  <   error: "optional error"
   168  < }
   169  ```
   170  
   171  * **Bad response: some locks may have matched, but the server encountered an error**
   172  ```
   173  < HTTP/1.1 500 Internal error
   174  < Content-Type: application/vnd.git-lfs+json
   175  <
   176  < {
   177  <   locks: [],
   178  <   error: "git-lfs/git-lfs: internal server error"
   179  < }
   180  ```