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.

Stripe Errors

{
  "error": {
    "message": "Your card was declined.",
    "type": "card_error",
    "code": "card_declined",
    "decline_code": "generic_decline",
    "charge": "ch_12345"
   }
}

PayPal Errors

{
  "name": "ERROR_NAME",
  "message": "ERROR_DESCRIPTION",
  "information_link": "ERROR_DOCUMENTATION_LINK",
  "details": [
    {
      "field": "field_name",
      "issue": "problem_with_field"
    },
    {
      "field": "xxx",
      "issue": "xxx"
    }
 ]
}

Coinbase Errors

{
  "errors": [
    {
      "id": "validation_error",
      "message": "Please enter a valid email or bitcoin address"
    },
    {
      "id": "xxx",
      "message": "xxx"
    }
  ]
}

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

curl https://api.stripe.com/v1/charges \
  -X POST \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d amount=2000 \
  -d currency=usd \
  -d source=tok_mastercard \
  -d description="My First Test Charge (created for API docs)"

{
  "id": "ch_1GJn4t2eZvKYlo2Cl5T5QMiy",
  "object": "charge",
  "amount": 2000,
  ...
  "status": "pending",
  ...
}

Retrieve a Charge

curl https://api.stripe.com/v1/charges/ch_1GJn4t2eZvKYlo2Cl5T5QMiy \
  -X GET \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc

{
  "id": "ch_1GJn4t2eZvKYlo2Cl5T5QMiy",
  ...
  outcome: {
    network_status: "declined_by_network",
    reason: "expired_card",
    ...
  },
  ...
  "status": "failed",
  ...
}

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.