Get started with Jsonary and JSON Hyper-Schema

a quick guide to getting going

Extract the bundle

The bundle contains the Jsonary library, a standard set of renderers, and an in-browser AJAX-based "generic client", which can navigate APIs using JSON Hyper-Schema.

The contents of the bundle must be placed somewhere where cross-domain requests are not an issue (therefore, probably on the same server as your API).

Navigate to the bundle in your browser

If you navigate to the bundle in your browser, you should see a page a bit like this one.

At this point, you should be able to enter a URL from your JSON API, and see it displayed.

Reference a hyper-schema

Now, you need to modify the HTTP headers for that page, to reference a hyper-schema. The simplest way to do this is using the profile= parameter on the Content-Type header:

Content-Type: application/json; profile=/path/to/hyper-schema

You probably don't have a hyper-schema ready, so an example schema is provided in the bundle directory, called example-schema.json. The result should look something like this - you should see the data annotated with the title of your schema.

Edit your hyper-schema

Now, you can create your own hyper-schema, and reference that instead of the example one. Refreshing the page should re-fetch the data and the schema, so you can see the effect your changes have made.

If your schema is a static file, and you are not seeing your changes appear, you may find it is being cached by your browser.

The end result should be something like this, with the schema titles and links annotated on your data. Clicking the links should navigate the client to the new URL, or present a form/confirmation dialog if necessary. As you describe more and more of the API with hyper-schemas, the client should start to be able to interact with it.

Where next?

Once you have a client working, you can start adding custom renderers for particular parts of your API. This page should give you a good start.

Modifications

Your API might require some small modifications that cannot be covered by the schema - authentication, for example. The code for the "generic client" is fairly small, and it should be straightforward to modify it appropriately.

The most common modification is to add information (such as an OAuth token) to all outgoing requests. For this, you probably want to use a "link pre-handler" - a callback which is called before all links are followed:

Jsonary.addLinkPreHandler(function(link, dataToSubmit) {
	if (dataToSubmit.basicType() == "object") {
		dataToSubmit.property("access_token").setValue(accessToken);
	}
});

You will also probably want to modify the navigateTo() function (the line where it calls Jsonary.getData() to include the token.