Representational State Transfer (ReST) has gained widespread acceptance across the Web as a simpler alternative to SOAP- and Web Services Description Language (WSDL)-based Web services.
Representational State Transfer (ReST) is an architectural style for designing distributed systems, not a standard, but rather a set of conventions
Different actions are defined for each of the HTTP methods GET,DELETE,POST,PUT. Since some browsers do not support sending PUT and DELETE requests there is a simple work around for this limitation by including a _method parameter in the query string or parameters of an HTTP request.
HTTP has provisions for several mechanisms for "content negotiation" - the process of selecting the best representation for a given response when there are multiple representations available.
— RFC 2616, Fielding et al.
Content negotiation is the process of selecting one of multiple possible representations to return to a client, based on client or server preferences.
For example, given the following Accept
header:
application/json, application/xml
The returned results will be in JSON format.
The order of the Accept formats matter the first compatible format will be returned. Given the following Accept
header:
application/pdf, application/xml
The results will be returned in XML format for ReST services that don't natively return PDF.
The _accept parameter will override the Accept HTTP header.
http://shorten.stsoftware.com.au/ReST/V1/shorten?q=So%20happy%2C%20hitting%20the%20keyboard%20to%20buy%20a%20plane%20ticket%20for%20the%20sixteenth...%20supposed%20to%20be%20sunny%20with%20no%20clouds!%20%20&min=100&max=140
ReST services without any permissions defined can be called by any user whether logged in or not. If any permissions are defined for a service and the client call is not logged in a 401 ( unauthorized ) will be returned. If the client is logged in but without sufficient permission to run the ReST service 403 ( Forbidden ) will be returned.
Magic numbers gives access to this ReST service based on a special unique random key. The “magic number” can be limited to a period or number of calls. The properties of a “magic number” override any parameters in the ReST service call.
ReST services are used by external clients, notice of deprecated services and the removal must be done with care. When a service is marked as deprecated a message and the EOF ( end of life) date (if specified) will be added to the response
A Java plug-in can be defined to override the default behaviour of the system.
The stSoftware API attempts to return appropriate HTTP status codes for every request.
Code | Text | Description |
---|---|---|
200 | OK | Success! |
304 | Not Modified | There was no new data to return. |
400 | Bad Request | The request was invalid or cannot be otherwise served. An accompanying error message will explain further. In API v1.1, requests without authentication are considered invalid and will yield this response. |
401 | Unauthorized | Authentication credentials were missing or incorrect. For a ReST definition which requires a login. |
403 | Forbidden | The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. |
404 | Not Found | The URI requested is invalid or the resource requested, such as a user, does not exists. Also returned when the requested format is not supported by the requested method. |
405 | Method not allowed | The ReST definition was found but there is no command for the request method |
500 | Internal Server Error | Something is broken. |
Error Messages
When the Twitter API returns error messages, it does so in your requested format. For example, an error from a JSON method might look like this:
{"errors":[{"message":"no ReST definition FOO","code":"400.1"}]}