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.
- 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.
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).
The full guide and API documentation are located at fortunejs.com.
Here is a minimal application:
var fortune = require('fortune');
var app = fortune();
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) |
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
- Ember Data: the original implementation, it needs a custom adapter to actually work.
For release history and roadmap, see CHANGELOG.md.
Fortune is licensed under the MIT license, see LICENSE.md.