The jsonhome example Application

This is slightly outdated. We have four examples now, including a hello-world.

Structure of Example

The example project is using the Spring framework to realize a very basic RESTful web shop. There are two Spring controllers plus two controllers provided by the jsonhome-spring module. These controllers are described in the following sections.

##StorefrontController

A very simple storefront of the example web shop. The storefront only has one resource in text/html representation. The code is looking like this:

@Controller
@RequestMapping(value = "/storefront")
@Rel("/rel/storefront")
public class StorefrontController {

    @RequestMapping(produces = "text/html")
    public String getStorefront() {
        return "example/storefront";
    }

}

As you can see, this is a very straightforward Spring controller, serving a html document for /storefont. There is only one additional annotation: @Rel("/rel/storefront"). This annotation is part of the jsonhome4spring library. It specifies the link-relation type of the storefront resource.

The value of the @Rel annotation has the same semantics as the relattribute in HTML stylesheet links: <link rel="stylesheet" href="http://example.org/foo.css" type="text/css" /> It specifies the type of the relationship - not the representation of the resource. You may translate the link as "this resource has a 'stylesheet' relation to the 'text/css' representation of the resource 'http://example.org/foo.css'".

The json-home representation of the storefront resource is looking like this:

{ resources : {
"http://localhost:8080/jsonhome-example/rel/storefront" : {
      "href" : "http://localhost:8080/jsonhome-example/storefront",
      "hints" : {
        "allow" : [
          "GET"
        ],
        "representations" : [
          "text/html"
        ]
      }
    }
...

This resource is basically telling us, that there is a link-relation type /rel/storefront, that is accessible by GETting the /storefront resource in text/html representation.

If you are following the href (for example by opening the link in a browser), you will get the /storefront resource.

You can also open a human-readable documentation of the resource by following the link-relation type URL. This documentation is automatically generated by jsonhome using the Spring annotations in addition to the annotations provided by the jsonhome-core module (and some Freemarker templates currently contained in the jsonhome-example module).

ProductsController

The ProductsController is a little bit more interesting. There are a few methods to GET one or all products, a method to PUT a product and a method to POST a product.

@Controller
@RequestMapping(value = "/products")
public class ProductsController {

...

    @RequestMapping(
            method = RequestMethod.POST,
            consumes = "application/x-www-form-urlencoded"
    )
    @Rel("/rel/products")
    public ModelAndView addProduct(final @RequestParam String title,
                                   final @RequestParam String price,
                                   final HttpServletResponse response) {
    ...
    }

    @RequestMapping(
            value = "/{productId}",
            method = RequestMethod.GET,
            produces = "text/html"
    )
    @Rel("/rel/product")
    public ModelAndView getProduct(final @PathVariable long productId) {
...

At class level, there are only the usual Spring annotations.

The methods are specifying two link-relation types: /rel/products and /rel/product. The POST method is consuming application/x-www-form-urlencoded representations. Getting a single product is only serving text/html. The interesting part in this case is the RequestMapping's value: /products/{productId} is an URI template.

The corresponding json-home document for these two methods:

    "http://localhost:8080/jsonhome-example/rel/product" : {
      "href-template" : "http://localhost:8080/jsonhome-example/products/{productId}",
      "href-vars" : {
        "productId" : "http://localhost:8080/jsonhome-example/rel/product#productId"
      },
      "hints" : {
        "allow" : [
          "GET",
          "PUT"
        ],
        "accept-put" : [
          "application/x-www-form-urlencoded"
        ],
        "representations" : [
          "text/html"
        ]
      }
    },
    "http://localhost:8080/jsonhome-example/rel/products" : {
      "href" : "http://localhost:8080/jsonhome-example/products",
      "hints" : {
        "allow" : [
          "GET",
          "POST"
        ],
        "accept-post" : [
          "application/x-www-form-urlencoded"
        ],
        "representations" : [
          "text/html"
        ]
      }
    }

The accept-post and accept-put attributes are generated using Spring's RequestMapping#consumes attribute. Also note the href-template and href-vars attributes of the /rel/product link-resource type: using these information, the final href can be generated.

JsonHomeController

The JsonHomeController is not part of the jsonhome-example, but provided by jsonhome-spring. It is responsible for serving the json-home documents in application/json-home, application/json and text/html format.

All Spring controllers using the @Rel annotations will be contained in the json-home document.

The URL used to access the json-home document is /json-home.

RelController

This controller is generating the human-readable documentation for a single link-relation type in HTML format.

The URL used to access link-relation types is /rel/{relationtype}.