GateIn REST API Specification

Version 2

    Status

    Initial Design

     

    Note: Throughout the document (since this is in design phase) the spec will include "DP" (discussion points) that invite others to comment on. Often the dicsussion points will pertain to RESTful principles vs simplicity. Meaning sometimes RESTful solutions to problems offer complexity for both consumers and producers. However these RESTful principles exist for a reason and are often aimed to achieve scalability and maintainability.

    Introduction

    REST is a popular architecture to interface with services over the web, and the goal of a REST API for GateIn would be to expose GateIn resources over the web in a RESTful manner. The REST API should be simple to consume by a variety of clients, independent of platform and language. It will allow developers and administrators access to common GateIn resources and operations from outside the portal providing opportunites for better tooling and management.

    Specification

    HTTP Methods

    GET

    Used to retrieve the representation of a resource.

    POST

    Used to create a representation of a resource.

    PUT

    Used to update the representation of a resource.

    DELETE

    Used to delete the representation of a resource.

    HTTP Status Codes

     

    CodeDescription
    Success
    200 (Ok)

    Success !

    Your typical response for GET requests.

    201 (Created)

    Resource was created and is immediately available.

    Location header will point to newly created resource.

    Common for POST requests.

    204 (No Content)

    Request was successful however there is no content.

    Common for DELETE and PUT requests.

    Client Errors
    400 (Bad Request)

    Request was invalid.

    Proper error message will be returned in response giving more details.

    403 (Forbidden)

    Access denied.

    Typical when an authenticated user tries to access a resource they don't have rights to.

    404 (Not Found)No resource found matching request
    Server Errors
    500 (Internal Server Error)Something bad happened and server is unable to respond appropriately.

    Security

    The GateIn REST API will support basic auth where securing requests should be done over SSL. Users will only be able to view the resources they have rights to, and only modify resources they have rights to. Users that are administrators (/platform/administrators) will be able to view all resources and modify all resources.

     

    DP: Should we support other methods like OAuth ?

    Content Types

    Each resource controls the content types they support however JSON and XML are the formats that will be generally available. The default content type will be JSON.

    Content Negotiation

    Two ways content negotiation will be supported is through the Accept header and the format query parameter. The query parameter will take precedence when both methods are used for the same request. This is handy when modifying the Accept header is not feasible or convenient (like when viewing it in a browser).

     

             Format          Accept HeaderQuery Parameter
    json

    application/json

    application/vnd.gatein+json

    format=json
    xml

    application/xml

    application/vnd.gatein+xml

    format=xml

     

    The custom application/vnd.gatein+<format> content type gives the GateIn REST API more control on the actual representation of a resource, including being able to support versioning easier. However the generic application/json and application/xml content types are supported for simplicity.

     

    Pagination

    Note: All pagination may not be supported for the first iteration however the spec will try and flush the out the details for a future version.


    For collections that could possibly return large results, the max results shown per page is limited to 20 by default. The following query parameters control this behavior.


         Name         DescriptionDefault
    startThe first item to display (starting at 1)1
    limitNumber of items to show per page20

     

    DP: Pagination is something that is not handled well or at all internally. Would be nice to leverage public Java API pagination if supported.


    To page through results of a collection supporting pagination Link Headers will be provided as part of the response to control pagination.


          rel      Description
    nextThe URL to the next page of results
    prevThe URL to the previous page of results
    firstThe URL to the first page of results
    lastThe URL to the last page of results

     

    Example:


    Link: <http://localhost:8080/rest/api/users?start=11&limit=10>; rel="next", <http://localhost:8080/rest/api/users/start=91&limit=10>; rel="last"
    

     

    DP: Alternative to using link headers (which may not be well known and not so trivial to parse) is to include this as part of the representation (response entity-body).

    DP: Pagination is tricky in a stateless architecture since the results can change between requests. One strategy would be to keep state on the server and pass a token to the client which could expire if the collection changes.

    Versioning

    Note: Versioning may not be implemented for the first iteration however the spec will try and flush out the details for a future version.

     

    Versioning is a way to achieve backwards compatibility while being able to move the REST API forward. While introducing new fields doesn't always break compatibility (especially with JSON) deleting, renaming, etc are all parts of a moving project and the need for versioning may become important at some point. The spec proposes to handle versioning through content types.

    Format

     

    application/vnd.gatein.<version>+json
    

     

    Content Type         Version         
    application/jsoncurrent
    application/vnd.gatein+jsoncurrent
    application/vnd.gatein.v1+jsonversion 1

     

    Note: For clients concerned about the stability of the API, the version should always be included in the content type when sending the "Accept" header.

    Links

    Links can be part of a response if a field needs to point to the actual representation of that resource rather then including the content of that resource. For example navigation nodes point to pages, however instead of including the entire representation of a page in the navigation representation, a link will be used which will allow clients to follow if they wish to retrieve the representation for that page.

     

    Links will include two attributes, an href which is an absolute URL to the resource and a rel attribute indicating the link relation (what the link is representing) and will have format gtn:<resource-type>. For example a page link would have a rel value of gtn:page.

     

    Scope

    Scope can be used to determine how many levels of links to follow to include in the representation of a resource. For example a scope=1 would follow any links of the current representation and a scope=2 would follow the links of the current representation plus any links returned from following the first links.

    Resource URI's

    Base URI

    http://<host>:<port>/rest/api

     

    Note: All URI's below are relative to the base URI

    Site Resource

    /sites/{site-type}/{site-name}
    

     

    The following site URI's can be used to search and view sites depending on context. The response will include links to the actual site resource represented by the URI above. See pagination section on how results are returned.


    /sites
    

    Lists all sites.

     

    /sites/{site-type}
    

    Lists all sites of certain type. ie: portal, group, user.

     

    Page Resource

    /sites/{site-type}/{site-name}/pages/{page-name}
    

     

     

    Navigation Resource

    /sites/{site-type}/{site-name}/navigation/{node-id}
    
    • node-id will be the internal navigation uri. For example administration/registry would be the node-id for the application registry navigation node.

     

     

    Application Resource

    /applications/{app-type}/{app-id}
    /sites/{site-type}/{site-name}/applications/{app-type}/{app-id}
    
    

     

    • app-type: portlet, gadget, wsrp
    • app-id: will be different depending on app-type. Portlets will have format {app-ref}:{portlet-id}. So for the navigation portlet it would be web:NavigationPortlet. This also known internally as the contentId.

     

    User Resource

    /users/{user-id}
    
    • Representation of a user
    /user
    
    • For the currently authenticated user. So if logged in as john, this would be the same as going to /users/john

    Group Resource

    /groups/{group-id}
    

    Applications Registry Resource

    /registry/applications/categories/{category-name}
    

    References

    [1] HTTP Status codes: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

    [2] Link Headers: http://tools.ietf.org/html/rfc5988http://tools.ietf.org/html/rfc5988#section-5

    [3] Initial REST API design: https://community.jboss.org/wiki/GateInRESTAPI