update with details on PUT redirections
This commit is contained in:
parent
fc75a0fc0f
commit
e2cf4140f3
63
docs/api.md
63
docs/api.md
@ -43,7 +43,6 @@ scheme differs from the original request uri.
|
||||
< HTTP/1.1 302 Found
|
||||
< Location: https://some-other-site.com/{oid}
|
||||
<
|
||||
< --git-media.265b3cb3f0530aae9010780a30d92a898400a5582081b21a099d51941eff
|
||||
< {binary contents}
|
||||
```
|
||||
|
||||
@ -98,13 +97,73 @@ This writes the object contents to the Git Media server.
|
||||
* 200 - The object already exists.
|
||||
* 201 - The object was uploaded successfully.
|
||||
* 307 - The server is returning a different location to send the object. Clients
|
||||
should retry the PUT against the URL. The `Authorization` header must _not_ be
|
||||
should retry the PUT against the URL. See the Redirection section below.
|
||||
|
||||
The `Authorization` header must _not_ be
|
||||
passed through if the location's host or scheme differs from the original
|
||||
request uri.
|
||||
* 409 - The object contents do not match the OID.
|
||||
* 403 - The user has **read**, but not **write** access.
|
||||
* 404 - The repository does not exist for the user.
|
||||
|
||||
#### PUT Redirection
|
||||
|
||||
The Git Media API supports offloading storage concerns to a separate storage
|
||||
API. In addition to a 307 response, the Git Media API needs to return one or
|
||||
more headers so the client knows how to retry the request.
|
||||
|
||||
* `Location` (required) - This is an absolute URL of the new location to send
|
||||
the object.
|
||||
* `Git-Media-Callback` (optional) - This is an absolute URL of a location to POST
|
||||
with the success or failure of the redirected request.
|
||||
* `Git-Media-Set-*` (optional) - Instruct the Git Media client for setting other
|
||||
headers by setting response headers with this prefix.
|
||||
|
||||
##### Example client request
|
||||
|
||||
```
|
||||
> PUT https://git-media-server.com/objects/{oid}
|
||||
> Accept: application/vnd.git-media
|
||||
> Content-Type: application/octet-stream
|
||||
> Authorization: Basic ...
|
||||
> Content-Length: 123
|
||||
>
|
||||
> {binary contents}
|
||||
>
|
||||
< HTTP/1.1 307 Temporary Redirect
|
||||
< Location: https://simple-storage-service.com/objects/{oid}
|
||||
< Git-Media-Callback: https://git-media-server.com/callback
|
||||
< Git-Media-Set-Authorization: simple-storage-service-authentication-token
|
||||
```
|
||||
|
||||
##### Example client redirection
|
||||
|
||||
```
|
||||
> PUT https://simple-storage-service.com/objects/{oid}
|
||||
> Authorization: simple-storage-service-authentication-token
|
||||
> Content-Type: application/octet-stream
|
||||
> Content-Length: 123
|
||||
```
|
||||
|
||||
##### Example client callback
|
||||
|
||||
The client callback is only made if the 307 redirection returned a
|
||||
`Git-Media-Callback` header. The Git Media client then makes a POST to that
|
||||
URL with:
|
||||
|
||||
* `oid` - The String OID of the Git Media object.
|
||||
* `status` - The HTTP status of the redirected PUT request.
|
||||
* `body` - The response body from the redirected PUT request.
|
||||
|
||||
```
|
||||
> POST https://git-media-server.com/callback
|
||||
> Accept: application/vnd.git-media
|
||||
> Content-Type: application/vnd.git-media
|
||||
> Content-Length: 123
|
||||
>
|
||||
> {"oid": "{oid}", "status": 200, "body": "ok"}
|
||||
```
|
||||
|
||||
## OPTIONS objects/{oid}
|
||||
|
||||
This is a pre-flight request to verify credentials before sending the file
|
||||
|
Loading…
Reference in New Issue
Block a user