REST API Quick Reference Guide

REST API Examples

Verbs

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:

Errors

The following examples show how Stripe, PayPal, and Coinbase have implemented their error responses.

Stripe Errors

PayPal Errors

Coinbase Errors

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.

References

  1. HackerNoon — RESTful API Designing guidelines
  2. Vinjay — Best Practices for Designing a Pragmatic RESTful API
  3. Medium — REST: Good Practices for API Design

Passionate about Software Engineering, Finance, and the technology tools that help us in those endeavors.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store