github.com/saracen/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 ```