otto-de-legacy / jsonhome Goto Github PK

• Integration tests, checking the end-to-end functionality of:
  • Registry
  • Client
  • Examples.
• The examples are untested.

'Status' hint should be set to 'deprecated' if controller is annotated as deprecated.

http://tools.ietf.org/html/draft-nottingham-json-home-02#section-5.10

http://tools.ietf.org/html/draft-nottingham-json-home-02#section-5.6

groupId: de.otto
artifactId: jsonhome-core, jsonhome-generator, jsonhome-spring
version: 0.1-SNAPSHOT

json-home requires link relations to be unique (there must not be any entry in the "resources" object that has the same link relation)[1]

To enforce that consider making

de.otto.jsonhome.model.JsonHomeBuilder#resources

a Map<String, ResourceLink> instead of a List<ResourceLink>.

This might seem unnecessary, but I have seen some APIs that would produce duplicate link relations from how they are designed.

Jan

[1] See last paragraph in http://tools.ietf.org/html/draft-nottingham-json-home-02#section-3

• Provide some annotations
• Add description to ResourceLink and HrefVar
• Add the information to the generated documentation

• Integrate logback into the application
• find + remove the logging-TODOs
• developers should be able to find out what's going on in the generators, parsers, clients, registry, and so on.

If your RESTful application consists of several systems, each responsible for a number of REST resources (say: a web shop, consisting of a product-system and an order system) you may get one json-home document per system (product, order). The Server should be able to consume the separate json-home documents and offer an aggregated json-home document, containing the link-relations of all systems.
In addition to this, the server should be able to offer a human-readable version (HTML) of the documentation, just like the RelController of one system is offering a HTML representation of the json-home.

Depends on Issue #9.

• Return ETAG + Last-Modified when GETTING a Resource
• Check for modifications as specified in http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-19
• Use features implemented in issue #9

• Beside of Spring, other frameworks like JAX-RS may be used to write RESTful applications.
• Provide a Service Provider Interface (SPI) and skeleton implementation so it is easier to support JAX-RS or similar things.
• Introduce separate repositories for jsonhome-core, jsonhome-example, jsonhome-spring so it is possible to add a jsonhome-jaxrs or jsonhome-whatever.

• Client used to access JsonHome documents.
• Http and in-memory client.
• Support of HTTP caching.

http://tools.ietf.org/html/draft-nottingham-json-home-02#section-5.9:
" Hints that the resource requires state-changing requests (e.g., PUT,
PATCH) to include a precondition, as per
[I-D.ietf-httpbis-p4-conditional], to avoid conflicts due to
concurrent updates.

Content MUST be an array of strings, with possible values "etag" and
"last-modified" indicating type of precondition expected."

This is intended for PUT, POST and PATCH requests, so it is possible to check if a resource
has concurrently changed since the caller retrieved the last state of the resource.

In some situations it is not possible to simply rely on Spring annotations. For example, if you want to use hierarchical URIs, you have to do something like this to access the path from the requested URI:

GET /rel/product/form

@RequestMapping("/rel/**")
public ModelAndView getRelationshipType(final HttpServletRequest request)
final String requestURI = request.getRequestURI();
final String relationType = requestURI.substring(requestURI.indexOf("/rel/"));
final URI relationTypeURI = URI.create(rootUri().toString() + relationType);
...

In this case (there might be more situations), there are no @PathVariables of @RequestParam annotations, so the JsonHomeGenerator will not be able to discover the href-template and href-vars.

We need some annotations or some optional attributes in the Rel annotation to explicitly define the template like, for example:
@rel(
value="/rel/link-relation-types"
href-template="/rel{/path*}"
href-vars="/rel/link-relation-type#path"
)

• Implement Java tools to apply json-patch documents to an existing document.
• separate library, no dependencies to jsonhome4spring.

• No Spring dependencies.
• Separate Project / Module
• Depends on Issue #27

The HTML representation of the json-home module is not yet implemented in hellojersey.

The example should not have a copy of the Freemarker templates but should use the templates + css from the generator.

The extreme level of loose coupling that REST provides builds to a large extend on the idea of global[1](centrally owned and managed) specifications.

To emphasize that in the code, I suggest that you consider enforcing the value of the @rel annotation to be an absolute URI. Consequently, the support for serving link relation documentation from the very same service should be dropped, because it encourages service-owned link relations as opposed to centrally owned ones.

Jan

[1] While 'global' refers to a really centralized organization such as the IETF in the case of the open Web, 'global' in the intra-enterprise case could equally mean 'organization-wide'. Important is that contracts are not owned and managed by service owners.

In order to easily access a RESTful API having a json-home document, a client-side library should be implemented.

The client library must be implemented in a separate, optional module (for example: jsonhome4spring/client).

A second controller should be implemented, providing a generated documentation of the REST api described by the json-home document.

Because this will introduce a dependency to freemarker (or some other templating engine), this should be a separate, optional module (like jsonhome4spring/restdoc)

• Depends on Spring Release 3.2
• New hint accept-patch

• Add a form to the directresource.ftl
• Add a link to POST that opens the form
• Add information about required POST parameters (in case of accept-post = application/x-www-form-urlencoded)
• Add a text field to enter XML or JSON documents (depending on accept-post)

Markdown format could be used to add formatting to the documentation of link-relations or request variables.

A resource having a link-relation type like /rel/foo/bar is not resolved correctly. The name of the RelationType currently is "bar", but should be something like "foo bar" or something specified by an attribute Rel#name.

The LinkRelationTypeController is not finding a resource /rel/foo/bar.

• Remove the common base class
• Externalize the lookup of Rel-annotated controllers into a separate spring bean or class.
• split controllers by representation, not by resource, in order to be able to only use the json-home representation in case you do not want to have the HTML representation of the json-home resource.

In case of a POST request, the current default representation (used if no 'consumes' attribute is provided in the RequestMapping) returned by the JsonHomeGenerator is "text/html".

Should be application/x-www-form-urlencoded (using accept-post hint).

• Add a form to the directresource.ftl
• Add a link to PUT that opens the form
• Add information about required PUT parameters (in case of accept-put = application/x-www-form-urlencoded)
• Add a text field to enter a document (depending on accept-post) and prefill it with results from GET

see http://tools.ietf.org/html/draft-nottingham-json-home-02#section-5.7

• currently, you have to copy lots of stuff, including Spring magic, from the example into your application.
• It should be very easy, to add json-home support including the optional generation of HTML representations to an existing app.
• it should NOT be necessary to take anything from the example application.
• it should be possible, to override CSS of templates without too much configuration.

Implement support of accept-put hints.

From the draft (http://tools.ietf.org/html/draft-nottingham-json-home-02#section-5.8):

" Hints the location for human-readable documentation for the relation
type of the resource.

Content MUST be a string containing an absolute-URI [RFC3986]
referring to documentation that SHOULD be in HTML format."

• Documentation will be generated from the information already present in the source code of the Spring controllers, including the annotations provided with this library.
• It should be possible to link to a separate documentation using optional 'docs' attributes in the annotations. In this case, the value of the attribute is used instead of the link of the generated documentation.
• It should be possible to completely switch off the generation of documentation.

Currently the registry is not secured. Everybody should be able to GET the json-home document, but only some people or systems should be able to register or unregister json-home documents.

HMAC authentication will be supported to secure the registry.

• Parse RequestParam annotations.
• Add the request parameters to the domain model.
• Add the request parameters as query parameters to the generated href-template.

A RESTful website may consist of different, separated applications. In order to provide one global json-home document, it should be possible to parse and merge multiple json-home documents into one single document.

• Property rootURI is only used to generate links to the REST resources.
• New property rootRelURI (or something more properly named) will be used to generate links to the relation types (that is, the REST documentation).

The DocController is currently only available for jsonhome-spring. It should be implemented for jersey, too.

The Wiki page about the DocController must be updated after fixing this issue.

• Add the form using the href-vars.
• Add a possibility to select one of the supported representations.
• Open the form by clicking on GET
• Show the response in a pretty-printed presentation.

Currently, the URI of the href-vars are generated from the link-relation type.
With this enhancement, developers should be able to specify the URI of a href-var.
The URIs of the href-vars must be resolvable, pointing to the documentation.

Currently, the Rel annotation and the Doc annotation are separate; both can occur multiple times add controller or method level. This leads to some confusion because it seams that Doc is documenting the method, not the link-relation type.
The usage of a link-relation type and the definition of a link-relation type should be separated. The documentation belongs to the definition of the link-relation, not the usage.
It might be better to add the definition of one or more link-relation types including documentation to the (at most one) controller. The usage of the link-relation types may stay as it is.

One controller will then be responsible for zero to many link-relation types.
Every definition of a link-relation type may have documentation, or links to documentation. The Doc annotation should only be used for path variables or request parameters.
One method will refer to zero or one link-relation type.
Two controllers should not be responsible for the same link-relation type. Otherwise it would be possible to add two different documentations to the same link-relation type, which is not very intuitive. The json-home library should accept multiple controllers for one type, but at least WARN the developer if the two types have different documentation.

• Tests if short names are accepted
• Adding a registry so the documentation is able to link to the specification.
• Add support of short names to the client

Implement support of accept-post hints.