-
Notifications
You must be signed in to change notification settings - Fork 5
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.
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.
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"}});
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."
}
}