The ShootProof API aims to use HTTP methods as close as possible to their defined semantics.
The HTTP specification has been split up into a collection of RFCs that, together, make RFC 2616 obsolete. For more information on HTTP semantics, refer to the following RFCs.
Use the OPTIONS method if it is unclear what HTTP methods a particular resource supports. The response to an OPTIONS request will include an Allow header that lists all methods available for use on the resource.
OPTIONS /studio/brand/a224a222-96c6-4779-8c19-f4d5c196ff7a/invoice HTTP/1.1
Authorization: Bearer 278c11427af7b311ca18a1171c089724
Host: api.shootproof.com
HTTP/1.1 204 No Content
Date: Wed, 01 Nov 2017 21:49:56 GMT
Allow: OPTIONS, GET, HEAD, POST
With few exceptions, most resources support the use of the GET method for retrieval.
Some resources support the use of content negotiation to tell the server what media type to return. The alternate link relation indicates when this is available and will include a type property to denote the media type available.
GET /studio/brand/a224a222-96c6-4779-8c19-f4d5c196ff7a/invoice/91a816b4-394c-4a7f-85ff-7ae6256fe7c2 HTTP/1.1
Authorization: Bearer 278c11427af7b311ca18a1171c089724
Accept: application/vnd.shootproof+json
Host: api.shootproof.com
HTTP/1.1 200 OK
Content-Type: application/vnd.shootproof+json
Date: Wed, 01 Nov 2017 22:35:35 GMT
{
"type": "invoice",
"id": "91a816b4-394c-4a7f-85ff-7ae6256fe7c2",
"links": {
"alternate": {
"href": "https://api.shootproof.com/studio/brand/a224a222-96c6-4779-8c19-f4d5c196ff7a/invoice/91a816b4-394c-4a7f-85ff-7ae6256fe7c2",
"type": "application/pdf"
},
"self": {
"href": "https://api.shootproof.com/studio/brand/a224a222-96c6-4779-8c19-f4d5c196ff7a/invoice/91a816b4-394c-4a7f-85ff-7ae6256fe7c2"
}
}
}
ShootProof uses the POST method to mean “create a new resource.” Creation of new resources is almost always done through the collection resource in which the new entity resource should appear.
When the response is a success, the body will contain the newly-created resource or a resource related to the action performed. For example, when using POST to send an email for an invoice, even though this creates a new email resource on the server, we respond with the invoice for which the email was sent. In these cases, the Content-Location header provided in the response indicates the canonical URL for the response body, and a status code from the 2xx series indicates success.
We do not use the POST method to update resources.
To fully update entity resources, we use the PUT method.
While the HTTP specification states PUT may be used to create resources, we use it only for replacing resources. This operation requires the full resource object be submitted to the server for processing. It effectively replaces the entity on the server with the one submitted.
Another way to think about the behavior of PUT in the ShootProof API is that it is an overwrite operation.
RFC 5789 adds the PATCH method to HTTP. While PUT is a full update process, overwriting the state of the resource on the server, PATCH provides a mechanism to support partial updates.
ShootProof uses the PATCH method for partially updating entity resources through sending one or more properties. We only make changes to the properties provided in the request body; all other properties are left unchanged, unless our internal rules for changing one of the submitted properties causes other data on the resource to change.
Additionally, we use the PATCH method to perform batch updates on collection resources.
We use the aptly-named DELETE method to remove entity resources.
Some collection resources support the use of the DELETE method to remove batches of entities contained within the target collection.