otto-de-legacy / jsonhome Goto Github PK
View Code? Open in Web Editor NEWLibraries to publish and consume json-home documents for RESTful web applications.
License: Apache License 2.0
Libraries to publish and consume json-home documents for RESTful web applications.
License: Apache License 2.0
groupId: de.otto
artifactId: jsonhome-core, jsonhome-generator, jsonhome-spring
version: 0.1-SNAPSHOT
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)
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.
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.
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.
Implement support of accept-post hints.
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).
The HTML representation of the json-home module is not yet implemented in hellojersey.
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.
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."
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.
Markdown format could be used to add formatting to the documentation of link-relations or request variables.
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).
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.
Implement support of accept-put hints.
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.
The example should not have a copy of the Freemarker templates but should use the templates + css from the generator.
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
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.
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.
'Status' hint should be set to 'deprecated' if controller is annotated as deprecated.
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"
)
Depends on Issue #9.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.