REST API Quick Reference Guide
REST API Examples
- Stripe — The de facto standard
- PayPal
- GitHub
- IEX Trading
- Coinbase
Verbs
- GET — read
- POST — create/add
- PUT — replace (complete update)
- PATCH — modify (partial update)
- DELETE — delete
Status Codes
REST APIs typically use conventional HTTP response codes to indicate the success or failure of an API request. This Hacker Noon post provides a good description of the major status codes. In addition, the following Coinbase examples are helpful:
- 2xx — Success Category
200 OK — Successful request
201 Created — New object saved
204 No content — Object deleted - 4xx — Bad Request Category
400 Bad Request — Returns JSON with the error message
401 Unauthorized — Couldn’t authenticate your request
404 Not Found — No such object - 5xx — System Error Category
500 Internal Server Error — Something went wrong
503 Service Unavailable — Your connection is being throttled or the service is down for maintenance
Errors
The following examples show how Stripe, PayPal, and Coinbase have implemented their error responses.
Asynchronous Endpoints
For long-running requests, you have three options as listed below. You could take a phased approach in which your MVP requires consumers to keep the connection open. The next phase could be a polling mechanism, followed by the most advanced phase which could be a webhook method.
Keeping the connection open — Ask the client/consumer to keep the connection open longer. This might require modifying TCP connection settings (“idle-timeout” and/or “keep-alive”) on the client’s server and/or firewall.
Polling-Use a POST endpoint to create the transaction, and use a GET endpoint to poll its status. See the following Stripe example:
Create a charge
Retrieve a charge
Webhook Event Processing — As described in this post, best practices favor the webhook method, but what happens if the client’s “listener” is down? Then, your service should support retry logic as described in this example. Also, your service should support a query endpoint so that a client can query the status of an event in case the client missed all of the retries.
