General API Usage

Generally speaking, the Ayamel Media API speaks JSON. You can have content returned to you in json, xml or yaml. However, for sending data to the API, it expects to receive JSON.

API Responses

The API documentation describes the main data returned by each call to the API, however it currently does not describe the containing structures.

For example, a request to GET /resources/1232435 would return:

{
    "resource": {
        /* data structure defined in the API docs under `GET /resources/{id}` ... */
    },
    "response": {
        "code": 200,
        "message": "ok"
    }
}

Response data is included in the response body to give calling API clients more detail, particularly in cases of errors. The proper HTTP status codes and messages are set as they should be, but it may be easier for some clients to program against what is returned in the response body.

Response formats

You may return results in json, yml or xml. You can do this by specifying the _format parameter. By default json is returned. For example:

GET /resources/123456&_format=yml will return:

resource:
    #resource data structure
response:
    code: 200
    message: ok

You can also specify a jsonp format, but you must also provide the _callback parameter. For example:

GET /resources/12345&_format=jsonp&_callback=myFunction will return:

myFunction({"resource": {/* resource data */}, "response": {"code":200,"message":"ok"}});

Response code suppression

Some clients don't respect HTTP very well, and in some edge cases it may be necessary to always return a 200 OK response. If you need this, you can pass an extra _suppress_codes parameter to any API call.

In the case of an error on a call to PUT /resources/123456?_suppress_codes=true, the API would return a 200 OK response, however the response body would still contain what the response code should have been, along with a more descriptive error message:

{
    "response": {
        "code": 400,
        "message": "Resource.title is a required field."
    }
}