REST architecture style:
All data are available in the following format:
A dedicated cluster has been setup to allow access in better conditions to
which is deprecated and won’t be reachable at 2015-10-25
No need to use anymore
As a REST respectful web service implementation, Libcast web services declare just
a few root services addresses, and all other addresses have to be discovered browsing
the Libcast services.
/ gives access to
platform list and
Each data response includes a
href property to address the current data, other
related data and browse the services.
This way, the client do not have to construct URLs to request our resources. In order to minimize the amount of request in returning sessions, the REST client should cache the URLs and direct access them the next times.
If you want to paginate the results, include a Range HTTP header in the request. By default, no pagination is applied.
The server response is then:
The pagination is based on start/end offsets, not page index/size.
Indices are 0-indexed, so
Range: entities=0-4 with return 5 entities, from index
0 to index
Note that the response contains the total number of entities (
342 in the above example). You can use this information to control fetching.
At the moment, the
range-unit you specify must be
entities. Depending on the URL you are fetching, the paginated entities will be users, streams, resources… Furthermore, the RFC allows several ranges to be asked in a request but we handle
only the first one since it would make little to no sense to query discontinued ranges of entities.
Keep in mind that by requesting entities via ranged requests, you could miss some entities or have the same entity being sent twice because of insertions and deletions that may occur between two requests.
Although we don’t recommend it since you can experience slow response times, you can issue a request without range rule if you really need a full set of entities.
REST web services make usage of HTTP codes then you can easily understand what happened just from the returned HTTP code.
The following codes are used in our services:
400 Bad Request: the request can not be interpreted
401 Authentication Required: authentication is required to access the web services
404 Page Not Found: there is no resource at the HTTP address requested
406 Not Acceptable: the requested content type is not supported by Libcast web services
412 Erroneous Data: the submitted entity is invalid (a required field is missing, a constrained field is invalid…)
416 Requested Range Not Satisfiable: the
RangeHTTP header is malformed
500 Internal Error: the server encountered an internal error
200 Ok: update successful
204 No Content: deletion successful
Other status can be used in the future. All status codes respect the HTTP 1.1 specification.
Libcast web services use HTTP Digest HTTP Digest Authentication) to authenticate the emitter of an API request. Each Libcast user has an API key which does not change in time (unlike the user password) and is used to issue signed API request.
An initial request is required to ask the realm to the server:
Let assume that the client user is
scott and his API key is
The client first declares some variables:
uri = / nc = 00000001 // request counter cnonce = MDE1OTgz // client nonce
And then the digest is generated:
ha1 = md5(username:realm:api_key) = f420c8e397552883627180504b2604d2 ha2 = md5(method:uri) = c7bdbbd1236664e402675e9205623312 response = md5(ha1:nonce:nc:cnonce:qop:ha2) = ce03e928168e154c7a9fc20b817a6d8a
And a new request is issued:
The nonce has a defined lifetime so other requests can be issued with the same
nonce. The client has to change the
nc and, consequently, the
response for in additional request.
Note that the HTTP Digest authentication can be easily tested with cURL:
Curl automatically sends a first request to get the realm, and then an authenticated request to get the data.
When issuing an update, you can provide only the updated fields in the request, the other fields will not be modified. If you want to clear the content of a field, you have to include it in the request with no value.
A partial update is issued with a HTTP PUT method since the PATCH method (RFC proposal for partial updates) is not available in the framework used by the web services.
Some services returns links to media files (thumbnail, video…). These medias are accessible while authenticated via the API client. If you want to access these medias later, you have to re authenticate but you can also cache them on the client side. This is specially interesting for thumbnails which are light but often used in client applications.
It is possible to upload a file from a form hosted on an external host under conditions. The usage of Plupload is required.
This is a commented example. Adapt the $config parameters to match your needs.
Save this file as index.php.
php -S localhost:8000
Type in your browser at http://localhost:8000
curl to test the web services.
Be aware that properties order can change in the response, and that Libcast modules
can add some properties to the responses too.