REST Responses

### Navigation

- index
- next |
- previous |
- fantastico 0.5.0-b126 documentation »
- Fantastico features »
- ROA (Resource Oriented Architecture) »

# REST Responses

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.

## Common responses

For each call there are some common responses that might be returned by APIs:

### Internal Server Error

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.

### Concrete errors

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>
>     }

## Resource Item

### Retrieve resource item

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"}

### Create a new resource item

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/123

>   > If 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"}

## Update an existing resource

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: 0

> - 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"}

### Delete an existing resource

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: 0

> - 400 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"}

### Bulk creation of items

Fantastico APIs do not support bulk creation of items. We do not intend to add this kind of capability.