arf

ARF - API Request/Response Formats

Requests

Always wrap your objects to future proof your APIs and make it very clear what objects you are passing in.

POST

{
  "product": {
    "name": "Ice cream"
  }
}

Updates - POST/PATCH

• should always try to have the ID in the url, eg: /v1/products/123
• but if you can't or don't, then the id can be passed in the object to update

{
  "product": {
    "id": "123",
    "name": "Blue ice cream"
  }
}

Responses

20X responses should return with an outer object label, eg:

{
  "product": {
    "id": "123",
    "name": "Ice cream"
  }
}

For multiple items being returned:

{
  "products": [
    {
      "id": "123",
      "name": "Ice cream"
    },
    {
      "id": "456",
      "name": "chocolate bar"
    },
  ]
}

For deletions or things where an action was taken, but not object should be returned:

{
  "message": "Thing deleted successfully"
}

Error Responses

This matches up with JavaScript error.message.

{
  "error": {
    "message": "something bad happened",
    "status": 400
  }
}

• Status is optional, can read the response.status if needed, but nice to have in the error object.
• We use status here instead of code so it matches Response.status.