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

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).

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.

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.

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

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