json-schema-agent-component

JSON Hyper-Schema HTTP client

json-schema-agent

Please note this library is not ready for production use.

JSON Hyper-Schema HTTP REST client. Together with json-schema-core and json-schema-hyper, this library provides a basic mechanism for correlating instances with schema over HTTP. It also provides validation of request and response messages (schema and targetSchema), if json-schema-valid is used.

Refer to the JSON Schema Core v4 and Hyper-Schema IETF Internet Draft specs for more info.

component:

$ component install ericgj/json-schema-agent

npm:

$ npm install json-schema-agent-component
 
// Simple GET 
 
var agent = new Agent();
agent.get('http://some.uri/path', function(err,correlation){
  correlation.instance  // the JSON instance (parsed body of response) 
  correlation.schema    // the schema 
})
 
 
// POST using link attributes 
 
var link = { href: 'http://example.com/thing',
             rel: 'create',
             mediaType: 'application/vnd.thing+json'
           }
 
agent.post(link, obj, fn);
 
// or automatically follow method defined in link 
 
link.method = 'POST'
agent.follow(link, obj, fn);
 
 
// follow chain of links 
 
agent.follow(link, function(errcorrelation){
  var nextItem = correlation.rel('next');  // find link rel="next" in the schema 
  agent.follow(nextItem, fn)
})
 
 
// fetch and dereference schema from link 
// note schema is cached to the agent 
 
agent.getSchema(link, function(err,schema){
  schema    // the parsed, dereferenced schema 
})
 
 
// dereference raw schema object 
 
agent.dereference(data, function(err,schema){
  schema    // the parsed, dereferenced schema 
})
 
 
// Configuration 
 
// set default base uri for resolving relative URIs in links 
// in-browser, typically you'd want to set this to window.location.origin 
 
agent.base('http://example.com/api'); 
 
 
// set underlying http client (class) 
var httpClient = require('superagent');
Agent.service(httpClient);
 
 
  1. Unit tests:
  • browse to file:// test/index.html
  • browse to file:// test/refs.html
  1. Functional tests:
$ node test/server.js

And browse to http://localhost:3000/functional.html

  1. Unit tests:
$ npm test
  1. Functional tests:
$ node test/server.js &
$ mocha --ui bdd test/functional.js

MIT

  • Note that an underlying HTTP client library must be specified, it is not built-in. The API for requests/responses is equivalent to a simple subset of superagent's. So superagent is the easiest choice, but not the only one.

  • The Correlation object is implemented in json-schema-core, and extended in json-schema-hyper, qq.v. for more examples of usage.

  • Both Content-Type and Link header -style correlation methods are supported (see Core, sec. 8). However, specification of the root relation via the Link header (see Hyper-Schema, sec. 4.2), is not currently supported. This may be implemented in the future.

  • This library provides parsing of the media property within schemas, however the internal representation of media type values (i.e., the use of this information in parsing the values) is left for the upstream application.

  • The readOnly property within Link Description Object (LDO) schemas is not currently validated during write operations (POST/PUT/PATCH). It is not clear from the spec whether it is the responsibility of the client to do so.

  • The pathStart schema property is not currently validated when correlating instances (Hyper-Schema, sec. 4.5). This may be implemented in the future.

  • Likewise, the determination of authoritative representation of the self link target is not currently implemented (Hyper-Schema, sec. 5.2.2), but may be in the future.