Data formats

• Date and time will be expressed as ISO8601 date and time in UTC (e.g., "2015-09-23T16:01:35Z").
• Floats will be represented as Strings with decimals separated by a dot "." (e.g., "169.99").

Accepted Media Types

The Ifeelgoods API returns mainly JSON documents (application/json). However, the API has the ability to generate and return e-cards directly as PDF documents (application/pdf).

Here the list of all the accepted types:

• application/json
• application/json; pretty=true (not to use in production)
• application/pdf

HTTP Status Codes

The Ifeelgoods API attempts to use appropriate conventional HTTP response codes. 2xx codes indicate succesfull requests, 4xx codes are intended for cases in which there is an error in the request and 5xx when the Ifeelgoods' servers are experiencing troubles (which is rare 😉).

Error handling best practice

In case of 5XX error, a good practice is to allow your system to retry the request (automatically or manually).
Sometimes, 504 errors can occur (usually due to a temporary server overload), it does not means that the code has not been created on our side, you will be billed accordingly. A retry is possible thanks to idempotency.
Please refer to the following section in the FAQ to understand the importance of order_id in case of 5XX errors.

Responses for successful requests

Single resource

Every responses including a single resource provide a data section which contains the detailled resource object. In addition, some resources contain a version top-level attribute that helps prevent simultaneous updates of a resource from overwriting each other. When a PUT request is sent, the value should match the one stored in order to be accepted.

{
  "data": {...},
  "version": 42
}

Resources collection & pagination

{
  "data": {...},
  "paging": {
    "page": 1,
    "per_page": 20,
    "total": 214
  }
}

Response for errors

When the Ifeelgoods API returns error messages, response looks like this:

{
  "error_name": "not_found",
  "error_message": "The resource or action does not exist."
}

Error types