When working with resources API it is important to understand what responses might be returned in order to correctly consume them into your clients. In this document you can find success / exception responses coming from APIs.
For each call there are some common responses that might be returned by APIs:
When working in distributed environments there are unexpected situations occuring (server failing, dns failing, and so on). In all this cases a 500 HTTP Status code will be returned and an html generated page will be sent in the body of the error. Do not make assumptions about the format of this response as it might change in the future.
In Fantastico generated APIs, concrete errors follows a given format:
{ "error_code": <a numeric error code used for uniquely identifying the situation>, "error_description": <a user friendly message in English describing the error>, "error_details": <an http link where you can find more details about the error which occured> }
When retrieving a resource from a collection (GET /api/2.0/app-settings/1) the following responses might be returned:
200 OK
200 OK Content-Type: application/json Content-Length: 53 {"id": 1, "name": "default_locale", "value": "en_US"}404 Not Found
404 Not Found Content-Type: application/json Content-Length: 160 {"error_code": 10001, "error_description": "Resource 1 does not exist.", "error_details": "https://rcosnita.github.com/fantastico/html/features/roa/1000x.html"}
When creating a resource into a collection (POST /api/2.0/app-settings) the following responses might be returned:
201 Created
201 Created Content-Type: application/json Content-Length: 0 Location: /api/2.0/app-settings/123If you want to fetch the newly created resource just follow the location header.
400 Bad Request
400 Bad Request Content-Type: application/json Content-Length: 173 {"error_code": 10010, "error_description": "Resource 1 requires field (name|value).", "error_details": "https://rcosnita.github.com/fantastico/html/features/roa/1000x.html"}
When updating an existing resource (PUT /api/2.0/app-settings) the following responses might be returned:
204 No Content
204 No Content Content-Type: application/json Content-Length: 0400 Bad Request
400 Bad Request Content-Type: application/json Content-Length: 173 {"error_code": 10010, "error_description": "Resource 1 requires field (name|value).", "error_details": "https://rcosnita.github.com/fantastico/html/features/roa/1000x.html"}
When deleting an existing resource (DELETE /api/2.0/app-settings) the following responses might be returned:
204 No Content
204 No Content Content-Type: application/json Content-Length: 0400 Bad Request
400 Bad Request Content-Type: application/json Content-Length: {"error_code": 10020, "error_description": "Resource 1 is still in use.", "error_details": "https://rcosnita.github.com/fantastico/html/features/roa/1000x.html"}
Fantastico APIs do not support bulk creation of items. We do not intend to add this kind of capability.