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.
- 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]=robert@mailbert.com&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).
Custom type defines its own schema and hooks and might be injected to any resource's schema side by side to standard data types and incorporates its data hooks into the resources' ones. Usage example:
app.customType("date-timezone", {
date: String,
timeZone: String
}).beforeWrite([{
name: 'datetz2db',
priority: -1,
init: function() {
return function(req, res) {
return DateTz.todb(this)
}
}
}]).afterRead([{
name: 'datetz4db',
priority: 1000,
init: function() {
return function(req, res) {
return DateTz.fromdb(this);
}
}
}])
app.resource("schedule", {
...
arrival: 'date-timezone'
...
})
The datetz2db and datetz4db will be automatically attached to the parent resource hook chain.
The full guide and API documentation are located at fortunejs.com.
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) |
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.
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.