Recent Posts

    Authors

    Published

    Tag Cloud

    How to define a RESTful Web Services?

    ReST services can be used natively from a client libraries such as jQuery

    Overview

    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.

    The resources are acted upon by using a set of simple, well-defined operations. The REST architectural style constrains an architecture to a client/server architecture and is designed to use a stateless communication protocol, using HTTP/HTTPS.
     
    The system allows a series of RESTful services to be defined. The ReST service will normally return a JSON object when successful. Other formats can be requested by the "accept" header. 
     

    Representational State Transfer (ReST) is an architectural style for designing distributed systems, not a standard, but rather a set of conventions

      • Client/Server, Stateless, Uniform Interface etc. 
      • "... more what you'd call 'guidelines' than actual rules" ~ Captain Barbossa. 
     

    Faking the HTTP Method with _method parameter

    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.

    Content negotiation with _accept parameter

    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.  

    Example

    ReST example

     

    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

    JSON result

    ReST definition

    ReST menu 
    A ReST definition has four SQL definitions:-
    1. HTTP GET calls the Retrieval SQL
    2. HTTP POST calls the Create SQL
    3. HTTP PUT calls the Update SQL
    4. HTTP DELETE calls the Delete SQL
    ReST definition 

    ReST permission

    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.

    ReST permission

    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 magic number

     

    ReST deprecation & removal

    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 

    ReST deprucation

    ReST - deprecated message

    ReST plugin

    A Java plug-in can be defined to override the default behaviour of the system. 

    ReST Plugin Process

    Changes the default data source to be used.

     

    HTTP Status Codes

    The stSoftware API attempts to return appropriate HTTP status codes for every request.

    CodeTextDescription
    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"}]}