The Phraseanet APIs use many standards you can find in other APIs. Requests are GET or POST requests, returning YAML, JSON or JSONP.
Parameters must be sent as HTTP key / values.
As Phraseanet API uses oAuth2 for authentication, you have to setup your server/do you requests with https.
There is no Rate Limit in v1, so you do as many requests as you wish.
There is no public access to Phraseanet API for the moment
All responses are wrapped in an object containing two fields : response and meta. Response is by default sent as JSON data.
Note
An optional timers fiels, providing an array of timers, can be retrieved by activating this feature. Read the configuration doc to enable it.
Timer example :
{
"meta": {
....
},
"response": {
....
},
"timers": [
{
"name": "api.load.end",
"memory": 1908328,
"time": 0.0025968551635742
},
{
"name": "api.result",
"memory": 3885680,
"time": 0.033026933670044
}
]
}
As of HTTP specification, you have to set an ‘Accept’ header if you want to fetch YAML.
Request :
curl -H 'Accept: application/yaml' ...
Response :
meta:
api_version: '1.2'
request: 'GET /api/v1/feeds/288/content/'
response_time: '2011-07-27T16:36:33+02:00'
http_code: 200
error_type: null
error_message: null
error_details: null
charset: UTF-8
response:
....
Request :
curl -H 'Accept: application/json' ...
Response :
{
"meta": {
"api_version": "1.3",
"request": "GET /api/v1/feeds/288/content/",
"response_time": "2011-07-27T15:52:04+02:00",
"http_code": 200,
"error_type": null,
"error_message": null,
"error_details": null,
"charset": "UTF-8"
},
"response": {
....
}
}
In order to fetch JSONP, you just have to add a callback HTTP parameter to your request.
Request :
curl -H 'Accept: application/json' /api/v1/my/request/?callback=foobar
Please note that in the case of JSONP, the API always returns 200 (except for HTTP 500’s) so your code can proceed the results ; you can have the true HTTP Code in the meta section.
Response :
foobar({
"meta": {
"api_version": "1.3",
"request": "GET /api/v1/feeds/288/content/",
"response_time": "2011-07-27T15:52:04+02:00",
"http_code": 200,
"error_type": null,
"error_message": null,
"error_details": null,
"charset": "UTF-8"
},
"response": {
....
}
})
The meta section contains few values, among “http_code”, “error_message” and “error details”.
Phraseanet API uses the appropriate HTTP status codes.
This code is repeated in the meta of the response, and the error_message is added.
You will find explanation below:
| HTTP Code | Meaning |
|---|---|
| 400 | Parameter is invalid or missing |
| 401 | The OAuth token was provided but was invalid |
| 403 | Access to the requested resource is forbidden |
| 404 | Requested resource is not found |
| 405 | Attempting to use POST with a GET-only endpoint, or vice versa |
| 500 | Internal Server Error |