Initial GateIn REST API Design

OUTDATED - For current spec and discussion please check: GateIn REST API Specification

An initial design for the REST API which will be used to spur discussion for the REST API design

Scope

• a RESTful web service which will provide a means of interacting with the GateIn portal server.
• The web service will interface with the portal server using the java based api. This service should provide, as much as possible, the same level of functionality as the java api. Some functionality will be limited, for example the more robust query features the java api provides as this is beyond the scope of a restful web service.
• The web service will use the GateIn jax-rs implementation (technically the eXo WS implementation which is provided in GateIn by default). It will be written as much as possible to be jax-rs implementation agnostic. Since its using the build in rest service, each portal will have its own endpoint.
• For the initial version, it will be protected to be only available to an administrator type user. The next version will change to return content based on the currently logged in user.
• initial version will support xml representations only. json support is planned (but need to find a better way to handle json than the current eXo WS jax-rs implementation support. The json representation should be based on xml/jaxb, not on the object itself)

HTTP Method Conventions

• GET
  • used to retrieve the resource's representation
• POST
  • used to create a new resource
  • other more generic cases (specific to individual resources)
• PUT
  • used to update a resource, will not be used to create a new resource (see POST)
  • should support conditional requests (eg only allow an update if someone hasn't already modified the object first)
    • maybe not for the initial version
• DELETE
  • used to delete a resource's representation

• When dealing with collections resources:
  • POST on the collection resource will create a new item in the collection
  • PUT will have to be applied to the newly created resource to perform an update.
  • DELETE on a collection resource should delete all elements in the collection
  • example when dealing with something like {endpoint}/elements
    • to create a new element: POST on {endpoint}/elements returns a new element at fore example {endpoint}/elements/element1
    • to update this element use PUT on {endpoint}/elements/element1
    • to delete all elements, use DELETE on {endpoint}/elements
    • to delete an individual element, use DELETE on {endpoint}/element/element1

Links

• links will use a 'rel' option to specify the type of link being used (ie the same as atom links)
• GateIn specific links will start with gatein.<link:type> (eg, gatein.page, gatein.documentation, ....). We don't want to use the more standard link type relations (where when performing a get on the link relation type returns documentation about the link) since the links would change based on where the portal is running.

Query Strings

• generic query string parameters
  • limit
    • specify how many items to return per page
  • start
    • the first element to start displaying on a page

• scope
  • how many levels of links in a resource should be followed and returned as part of the representation
  • if dealing with hierarchical elements, this can be used to determine how many child nodes should be returned in the representation. eg. scope =2 then it will return the elements and its child elements (where the child elements will include a link to their children instead of the actual representation).
  • if dealing with non hierarchical elements, will determine how many links to follow to be returned. eg. scope=1 when trying to retrieve categories, would return a representation of the categories with links to their managed content. If scope=2, then it would return the categories and the managed content included in the representation.
• force
  • a generic option which can be used to override conditional requests.
  • for example, we might want to delete specific elements without having to check if we have the latest value or not.
  • TODO: this will probably not be included in the first version
• view
  • can be used to determine if we want to return a different type of representation
  • for example, when trying to retrieve a list of objects, view=object/full could return the full representation of the objects, while view=links would only return links to the specific resources.
  • TODO: not for the first version, may not actually use this

• resource specific query parameters
  • eg we only want to retrieve a list of objects with a specific parameter
  • eg {property.name}=foo
    • in this example, we want to return all elements in which the named parameter contains 'foo'
    • can use regex to determine what exactly should be matched
  • eg sortByAsc={property.name}
  • eg sortyByDesc={property.name}
  • TODO: determine how to pass a list of resource specific query parameters.
    • {resource:url}/querylist, {resource:url}?querylist, something along these lines
    • worst case scenario is to just include this list in the documentation
  • TODO: initial version may have limited functionality here.

Web Service Endpoints

Main Endpoint

• {host}/rest/api
  • provides links to
    • documentation
    • pages
    • navigation
    • contentregistry
  • read only

• NOTE: we are handling things like /rest/api/{resource} instead of something like /rest/api/{site:type}/{site:name}/{resource} since
  • pages can be 'owned' by a particular site, but still used in a node from another site. So we need a way to list all pages, regardless of what site actually owns it
    • ie a query on /rest/api/pages would return all pages regardless of site, but a query on /rest/api/portal/classic/pages would only return pages for the classic portal
  • the contentregistry and documentation are common between all sites

Documentation

• {host}/rest/api/documentation
  • need to provide our own web service specific documentation to describe how to create clients.
  • the link for documentation will point to and be hosted on the server running the portal. Allows users to customize or extend the service more easily. Documentation will also be available on the Gatein projects web site as part of the normal GateIn documentation.
  • representations will be in html and pdf format. Written using docbook. Just like the current documentation.
  • will need to provide documentation for: link relation types, representations, urls, etc..

Pages

• {host}/rest/api/pages
  • representation for a list of pages
  • includes all pages, regardless of the page type
  • eg. {host}/rest/api/pages?name=foo&limit=10
    • return the first 10 items with where the page name contains foo

• {host}/rest/api/pages/{page:type}
  • representation for a list of pages for a particular page type (ie portal, group, ...)

• eg {host}/rest/api/pages/portal/name=foo
  • returns all pages under portal which contains foo in its name

• {host}/rest/api/pages/{page:type}/{page:name}
  • representation for a page resource

ContentRegistry

• {host}/rest/api/contentregistry
  • provides links to
    • categories
    • to the content repositories

• {host}/rest/api/contentregistry/categories
  • returns a list of categories
  • defaults to scope=1 (ie returns only a list of categories with links to where to get the managed content for each category). scope=2 will return the list of managed content in the representation
    • same idea for queries (ie if scope=1 then only query categories and not their content).

• {host}/rest/api/contentregistry/categories/{category:name}
  • returns the category representation with links to its managed content

• {host}/rest/api/contentregistry/categories/{category:name}/{managedContent:name}
  • returns the managed content representation

• {host}/rest/api/contentregistry/content
  • returns a list of content repositories (eg portal, wsrp, gadget, ...)
  • {host}/rest/api/contentregistry/content?name=foo
    • will return all content which has a name which contains foo
    • dependent on scope variable to determine if searching content/applications or content types

• {host}/rest/api/contentregistry/content/{contentrepo:type}
  • the content repo object representation which contains the list of content available
  • eg contentrepo:type = portal, wsrp, gadget

• {host}/rest/api/contentregistry/content/{contentrepo:type}/{content:name}
  • the content
  • read only for things like portlets
  • for gadgets, PUT can be used to update the gadget, DELETE to delete, etc...
  • to create a new Gadget, use POST on {host}/rest/api/contentregistry/content/gadgets

Site/Navigation

• {host}/rest/api/sites
  • links to available sites

• {host}/rest/api/sites/{site:type}
  • links to the specific site types (portal, group, dashboard, ...)

• {host}/rest/api/sites/{site:type}/{type:id}
  • links to the different sites under the specific site type

• {host}/rest/api/sites/{site:type}/{type:id}/nodes/{node:id}
  • a specific node representation

TODO

• look into how to handle internationalization. For the first version we will just return the token instead of a resolving the token and returning the values. Internationalization will change in a future version anyways to get away from using java resources.
• look into how to handle values for specific users. For example, when retrieving a site, we should only return the pages that a specific user has permission to access