About this Fork
NOTE: This is a fork of holidayextra's jsonapi-server We have merged a lot of pending PRs on the original repo that we felt we would gain advantage from. The original project was coing a bit too slowly for our needs.
Differences from upstream
primaryKey is configurable
In upstream, keys are by default
uuid and are taken from DB, if
We instead use a different property
primaryKey, whose possible values are
uuid: Uses UUID v4 (generated from the client)
autoincrement: Uses AUTOINCREMENT integers
*In future there might be other types of primaryKeys if required.
relationship key type is configurable
When creating a field, you can state how to relate it
You'd want to use our version of jsonapi-store-[*] plugins with this as the original versions will not be compatible with this
The rest of the readme is verbatim copy of the original project
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
createing a resource
deleteing a resource
searching for many resources
finding a specific resource
updateing a specific resource
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-serverand 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
sequelizeto 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
- Suggested Project Structure
- Configuring jsonapi-server
- Automatic Swagger Generation
- Defining Resources
- Foreign Key Relations
- Chaining handlers together
- Custom Handlers
- Post Processing Examples
- Migrating from an existing express server
- Application metrics
You can have a complete json:api server providing a
photos resource with just this:
var jsonApi = ;jsonApi;jsonApi;jsonApistart;
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
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:
or, for GraphQL:
the example implementation can be found here