An API browser for the hal+json media type

Here is an example of a hal+json API using the browser:

http://haltalk.herokuapp.com/explorer/browser.html

HAL is a format based on json that establishes conventions for representing links. For example:

More detail about HAL can be found at http://stateless.co/hal_specification.html.

By default, the HAL Browser can’t assume there is any metadata. When you click on the non-GET request button (to create a new resource), the user must enter the JSON document to submit. If your service includes metadata you can access, it’s possible to plugin a custom view that makes use of it.

1. Define your custom view.

   Here is an example that leverages Spring Data REST’s JSON Schema metadata found at /{entity}/schema.

   var CustomPostForm = Backbone.View.extend({
   	initialize: function (opts) {
   		this.href = opts.href.split('{')[0];
   		this.vent = opts.vent;
   		_.bindAll(this, 'createNewResource');
   	},
   
   	events: {
   		'submit form': 'createNewResource'
   	},
   
   	className: 'modal fade',
   
   	createNewResource: function (e) {
   		e.preventDefault();
   
   		var self = this;
   
   		var data = {}
   		Object.keys(this.schema.properties).forEach(function(property) {
   			if (!("format" in self.schema.properties[property])) {
   				data[property] = self.$('input[name=' + property + ']').val();
   			}
   		});
   
   		var opts = {
   			url: this.$('.url').val(),
   			headers: HAL.parseHeaders(this.$('.headers').val()),
   			method: this.$('.method').val(),
   			data: JSON.stringify(data)
   		};
   
   		var request = HAL.client.request(opts);
   		request.done(function (response) {
   			self.vent.trigger('response', {resource: response, jqxhr: jqxhr});
   		}).fail(function (response) {
   			self.vent.trigger('fail-response', {jqxhr: jqxhr});
   		}).always(function () {
   			self.vent.trigger('response-headers', {jqxhr: jqxhr});
   			window.location.hash = 'NON-GET:' + opts.url;
   		});
   
   		this.$el.modal('hide');
   	},
   
   	render: function (opts) {
   		var headers = HAL.client.getHeaders();
   		var headersString = '';
   
   		_.each(headers, function (value, name) {
   			headersString += name + ': ' + value + '\n';
   		});
   
   		var request = HAL.client.request({
   			url: this.href + '/schema',
   			method: 'GET'
   		});
   
   		var self = this;
   		request.done(function (schema) {
   			self.schema = schema;
   			self.$el.html(self.template({
   			    href: self.href,
   			    schema: self.schema,
   			    user_defined_headers: headersString}));
   			self.$el.modal();
   		});
   
   		return this;
   	},
   	template: _.template($('#dynamic-request-template').html())
   });

2. Register it by assigning to HAL.customPostForm

   HAL.customPostForm = CustomPostForm;

3. Load your custom JavaScript component and define your custom HTML template.

   <script id="dynamic-request-template" type="text/template">
   <div class="modal-header">
     <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
     <h3>Make a non-GET request</h3>
   </div>
   
   <form class="non-safe" action="<%= href %>">
     <div class="modal-body">
       <p>Target URI</p>
       <input name="url" type="text" class="url" value="<%= href %>" />
       <p>Method:</p>
       <input name="method" type="text" class="method" value="POST" />
       <p>Headers:</p>
       <textarea name="headers" class="headers" style="height: 100px">
       Content-Type: application/json
       <%= user_defined_headers %>
       </textarea>
     </div>
     <% _.each(schema.properties, function(value, name) { %>
       <% if (!("format" in value)) { %>
         <input type="text" placeholder="<%= name %>" name="<%= name %>" />
       <% } %>
     <% }); %>
     <div class="modal-footer">
       <button type="submit" class="btn btn-primary">Make Request</button>
     </div>
   </form>
   </script>

All you should need to do is copy the files into your webroot. It is OK to put it in a subdirectory; it does not need to be in the root.

All the JS and CSS dependencies come included in the vendor directory.

• Provide feedback to user when there are issues with response (missing self link, wrong media type identifier)

• Give 'self' and 'curies' links special treatment