henricook/fortune

A framework for prototyping hypermedia APIs.

Fortune.js

Hello nerds. Fortune is a web framework for prototyping hypermedia APIs that implement the JSON API specification. It comes with a modular persistence layer, with adapters for NeDB (built-in), MongoDB, MySQL, Postgres, & SQLite.

Get it by installing from npm:

$ npm install fortune

Contributions welcome.

Changes since fork of daliwali/fortune

• Keyword style filtering on dates like today, yesterday, year ago, etc. Example: /people?filter[birthday]=yesterday
• Debug option for logging all db requests
• Select fields to return: /people?fields=name,age (see acdb09b)
• Specif express instance in fortune options (see 0413a74)
• Control if linked documents are included in the response /people?include=pets (see 92c80f3)
• Simple filter: /people?filter[prop]=value (see d3cea1c)
• Filter by id: /people?filter[pets]=23 (see 798e871)
• Subdoc filter: /people?filter[subdoc.prop]=value (see 37b17ba)
• Metadata/Schema /resources (see b1ac88f && eaa5661)
• Hooks like .beforeWrite, .afterRead, .beforeAll, ... (see 1df41c0 && a0b3fa6 && c877afa)
• Extended filter: lt, gt, lte, gte /people?filter={birthday:{lt:'2000-02-02',gte: '1900-02-02'}} (see 30a5462)
• Filter by regex, multiple filters and filter by related resource fields /pets?filter[owner][name][regex]=ally&filter[owner][soulmate]=55 (see c2910f1)
• Filter $in support /people?filter[houses][in]=53,67,88 (see 63ec0cb)
• Limit result set /people?limit=10 (see 0032589)
• Sorting and pagination /people?sort=name&page=2&pageSize=2 (see 4a725de)
• AND / OR for filters /people?filter[or][0][name]=Dilbert&filter[or][1][email][email protected]&sort=name (see 5c97137)
• Pass $-prefixed query modificators to db (see 434bcb2)

This is not a complete list but it should cover most of the changes. There may also be more commits which are not linked here. I recommend looking at the tests and commit log if you are unsure on how to use these features.

Features

Fortune implements everything you need to get started with JSON API, with a few extra features:

• Batteries included, Fortune handles routing and database interactions so you don't have to.
• Serializers and deserializers for JSON API, and other hypermedia formats (in the future).
• Hooks to implement application specific logic before/after interacting with resources.

It does not come with any authentication or authorization, you should implement your own application-specific logic (see keystore.js for an example).

Guide & Documentation

The full guide and API documentation are located at fortunejs.com.

Basic Usage

Here is a minimal application:

var fortune = require('fortune');
var app = fortune({ /* debug: true */ });

app.resource('person', {
  name: String,
  age: Number,
  pets: ['pet'] // "has many" relationship to pets
});

app.resource('pet', {
  name: String,
  age: Number,
  owner: 'person' // "belongs to" relationship to a person
});

app.listen(1337);

This exposes a few routes for the person and pet resources, as defined by the JSON API specification:

HTTP	Person	Pet	Notes
GET	/people	/pets	Get a collection of resources, accepts query ?ids=1,2,3...
POST	/people	/pets	Create a resource
GET	/people/:id	/pets/:id	Get a specific resource, or multiple: 1,2,3
PUT	/people/:id	/pets/:id	Create or update a resource
PATCH	/people/:id	/pets/:id	Patch a resource (see RFC 6902)
DELETE	/people/:id	/pets/:id	Delete a resource
GET	/people/:id/pets	/pets/:id/owner	Get a related resource (one level deep)

Unit Testing

Tests are written with Mocha, and are run against the built-in NeDB adapter, plus MongoDB & MySQL on Travis. You will also need to have the developer dependencies installed. To run tests:

$ npm test

Client-side Implementations

• Ember Data: the original implementation, it needs a custom adapter to actually work.

Meta

Example services

There are a number of example services in the examples folder. These are easily run, as an example :

• Clone this repo & navigate to it
• npm install
• node examples/projects.js - starts a fortune server on port 1337
• curl http://localhost:1337/projects - no projects are present
• curl -H "Content-Type: application/json" -X POST -d '{ "projects": [{"id": "568a98d3347547eb0c04122b", "name":"Test project" }]}' http://localhost:1337/projects - create a project NB, it would be normal to allow the server to generate the ID by not setting it
• curl -H "Content-Type: application/json" -X POST -d '{ "tasks" : [{ "name":"Test task", "links" : { "project" : "568a98d3347547eb0c04122b" } }]}' http://localhost:1337/tasks
• curl http://localhost:1337/projects/568a98d3347547eb0c04122b?include=tasks - retrieve the created project and it's related task

For release history and roadmap, see CHANGELOG.md.

Fortune is licensed under the MIT license, see LICENSE.md.