README.md

jsonapi-server

A config driven NodeJS framework implementing json:api and GraphQL. You define the resources, it provides the api.

Motivation / Justification / Rationale

This framework solves the challenges of json:api and GraphQL without coupling us to any one ORM solution. Every other module out there is either tightly coupled to a database implementation, tracking an old version of the json:api spec, or is merely a helper library for a small feature. If you're building an API and your use case only involves reading and writing to a data store... well count yourself lucky. For everyone else, this framework provides the flexibility to provide a complex API without being confined to any one technology.

A config driven approach to building an API enables:

• Enforced json:api responses
• Automatic GraphQL schema generation
• Request validation
• Payload validation
• Automatic documentation generation
• Automatic inclusions
• Automatic routing
• Automatic handling of relationships

Ultimately, the only things you as a user of this framework need to care about are:

• What are my resources called
• What properties do my resources have
• For each resource, implement a handler for:
  • createing a resource
  • deleteing a resource
  • searching for many resources
  • finding a specific resource
  • updateing a specific resource

We've created handlers to automatically map our config over to database solutions help people get off the ground:

• jsonapi-store-memoryhandler - an in-memory data store to enable rapid prototyping. This ships as a part of jsonapi-server and powers the core test suite.
• jsonapi-handler-chain - a handler to chain custom behaviour around an existing handler. This ships as a part of jsonapi-server. More info can be found here
• jsonapi-store-relationaldb - using sequelize to support PostgreSQL, MySQL, MSSQL, MariaDB and SQLite.
• jsonapi-store-mongodb - for MongoDB.
• jsonapi-store-elasticsearch - for Elasticsearch.
• jsonapi-store-dynamodb - !SIGNIFICANT WIP! for AWS DynamoDB.

We've also written a library to ease the consumption of a json:api compliant service, if GraphQL isn't your thing:

• jsonapi-client - for NodeJS and Browsers

Full documentation

• Suggested Project Structure
• Configuring jsonapi-server
• Automatic Swagger Generation
• Defining Resources
• Debugging
• Foreign Key Relations
• Chaining handlers together
• Custom Handlers
• Post Processing Examples
• Migrating from an existing express server
• Application metrics

The tl;dr

You can have a complete json:api server providing a photos resource with just this:

var jsonApi = require("jsonapi-server");

jsonApi.setConfig({
  port: 16006,
  graphiql: true
});

jsonApi.define({
  resource: "photos",
  handlers: new jsonApi.MemoryHandler(),
  attributes: {
    title: jsonApi.Joi.string(),
    url: jsonApi.Joi.string().uri(),
    height: jsonApi.Joi.number().min(1).max(10000).precision(0),
    width: jsonApi.Joi.number().min(1).max(10000).precision(0)
  }
});

jsonApi.start();

Your new API will be alive at http://localhost:16006/ and your photos resources will be at http://localhost:16006/photos. The GraphiQL interface will be available at http://localhost:16006/.

Show me a full example!

Fire up an example json:api server using the resources mentioned in the official spec via:

$ git clone https://github.com/holidayextras/jsonapi-server.git
$ npm install
$ npm start

then browse to the JSON:API endpoints:

http://localhost:16006/rest/photos

or, for GraphQL:

http://localhost:16006/rest/

the example implementation can be found here