EntityBroker RESTful URL support

Information

Describes the support which EntityBroker has for RESTful URLs and URLs which describe entities. All entities can support RESTful URLs and interactions by simply implementing capabilities (interfaces) in their EntityProvider.

REST support

• We define REST by the microformat spec here: http://microformats.org/wiki/rest/urls
  • This means the ability to read things via a well known URL: GET /prefix/id
  • Create new things: POST /prefix/new
  • Update existing things: PUT /prefix/id
  • Delete existing things: DELETE /prefix/id
  • Support for a standard set of HTTP status returns
  • Support for XML and JSON input and output
• EntityBroker has full support for the spec and provides capabilities to allow a developer to make their entities accessible via REST without writing much code at all (hopefully just calls to their logic layer methods)
  • The following EntityProvider capabilities come together to make up RESTful support
    • Inputable - defines the input formats allowed by format extension (e.g. html, xml, json, jpg), internal handling for html, xml, and json is provided via XStream and Jettison
    • InputTranslatable - (optional) Allows for complete control over input translation and bypasses the internal automatic handling
    • Outputable - define the output formats allowed by format extension (e.g. html, xml, json, png), internal handling fof xml and json is provided via XStream and Jettison
    • OutputFormattable - (optional) Allows for complete control over output formatting and bypasses the internal automatic handling
    • CollectionResolvable - resolve a collection of entities based on an entity space and optional search parameters
    • CRUDable - implement CRUD operations for an entity
      • Broken into 4 interfaces for each aspect of CRUD
  • For example, a developer who wants to make their entities support RESTful URLs would need to implement 6 methods, all of which can be implemented alone to provide partial support if desired
    Sample WebappEntityProvider which implements RESTful capability
  • RESTful capability

Describe URLs

• The describe URLs and functionality are there to support client side or external developers who need to learn about an entity
• HTML and XML output of describe data is available so it can be parsed if desired
• Describe support is completely automatic, no coding is required on the part of the EntityProvider author
• Simply go to http://server/direct/describe to see a description of all the entities in your system
• Simply go to the entity space URL with describe on the end to see a description of a single entity (http://server/direct/prefix/describe)

Sample URLs

• Describing entities:
  • http://localhost:8080/direct/describe
  • http://localhost:8080/direct/eval-evaluation/describe
  • http://localhost:8080/direct/webapp-entity/describe
  • http://localhost:8080/direct/webapp-entity/describe.xml

• Access to an entity space:
  • http://localhost:8080/direct/webapp-entity
  • http://localhost:8080/direct/webapp-entity.xml
  • http://localhost:8080/direct/webapp-entity.json

• Access to an entity:
  • http://localhost:8080/direct/webapp-entity/id0
  • http://localhost:8080/direct/webapp-entity/id0.xml
  • http://localhost:8080/direct/webapp-entity/id0.json

Request Handling Support

• Some special capabilities are defined which allow for complete control over the requests into the entity broker direct servlet if desired

1. RequestInterceptor
   Gives the EntityProvider author the ability to access the request and response before and after every request that comes into the entity broker for their entity space (prefix)
2. RequestAware
   Gives the EntityProvider author the ability to access the Request or Response (if one exists) in any method in their EntityProvider, this allows for access to headers or the ability to manipulate things as needed
3. RequestHandler
   Gives the EntityProvider author the ability to completely handle the request which comes in for their entities however they want, all internal handling is skipped when this is used so it allows for complete control over requests while still using the entity broker URL space