Skip to content
JSON Hyper-Schema HTTP client
JavaScript CSS
Find file
Latest commit 6235c3c Nov 26, 2013 @ericgj version bump
Failed to load latest commit information.
test fix infinite regress DoS'ing when missing fragment refs and cyclical … Nov 26, 2013
.gitignore version bump Nov 21, 2013
History.md
Makefile initial draft + unit test setup Sep 11, 2013
Readme.md
component.json version bump Nov 26, 2013
deref.js
index.js fix infinite regress DoS'ing when missing fragment refs and cyclical … Nov 26, 2013
linkheader.js add npm packaging, conditional requires Oct 16, 2013
package.json
workflow.md

Readme.md

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.

Installation

component:

$ component install ericgj/json-schema-agent

npm:

$ npm install json-schema-agent-component

Examples

  // 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(err, correlation){
    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);

API

Running tests

In browser:

  1. Unit tests:

    • browse to file:// test/index.html
    • browse to file:// test/refs.html
  2. Functional tests:

    $ node test/server.js

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

In Node-land:

  1. Unit tests:

    $ npm test
  2. Functional tests:

    $ node test/server.js &
    $ mocha --ui bdd test/functional.js

Notes

  • 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.

  • During dereferencing, missing fragment and external URI references yield errors.

  • Missing schemas referenced (via HTTP headers) in instance data yield errors. However, if there are multiple indicated schemas, any that are not missing will be correlated to the instance data, in addition to yielding errors for the missing ones. (This behavior may change.)

  • Cyclical references (i.e., schema A references schema B which references schema C, which in turn references schema A), are detected and yield an error.

Limitations

  • 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.

License

MIT

Something went wrong with that request. Please try again.