Categories


Authors

REST API Quick Reference Guide

REST API Quick Reference Guide

Rest+API-8.png

REST API Examples

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.

References

Tech Leadership Spectrum — Communication

Tech Leadership Spectrum — Communication

Tech Leadership Spectrums — Assessment Tests

Tech Leadership Spectrums — Assessment Tests