hobson
Lightweight, minimalistic approach to RESTful endpoints in express.
Get up and running with a fully functioning CRUD API, with minimum configuration. Get all the functionality of a fully loaded framework with only the smallest amount of configuration.
Highlights
The hobson framework follows a RESTful approach. It uses models to define database relations and resources to provide endpoints to query the database.
- Provides commonly used CRUD endpoints out of the box
- Easily add and configure endpoints
- Endpoints take a protected by default approach to ensure security
- Provides stateless authentication using tokens
- Mongoose is used to provide great schema validation, hooks, etc.
- Before and after hooks are provided
- Easily integrates with existing express apps
Install
Get started by installing hobson.
npm install --save hobson
Hobson uses mongoose under the hood as it gives us awesome schema validation features.
Usage
Hobson is straight forwards in that it has 2 main types of components; models and resources. Models handle data interations and resources provide easy to use API endpoints.
Step 1. Create a model with a schema
File: unicorn.model.js
const Schema = ; const unicornSchema = ; // unicornSchema is a mongoose schema which means you can create virtuals, methods, etc. on it. unicornSchema; moduleexports = unicornSchema; // returns the Unicorn model
Step 2. Create a resource from a model
File: unicorn.resource.js
const Resource = ;const Unicorn = ; const unicornResource = model: Unicorn ; // route configuration here... moduleexports = unicornResource;
Step 3. Connect to your express app
File: app.js
const hobson = ;const app = ; // add middlewares and configurations to express app... hobson;
Endpoints
All endpoints have a unique string ID by which you can use to access them. To access an resource's endpoint, use the get
method.
unicornResource;
To overwrite an endpoint, simply provide your endpoint configuration with the same ID value.
CRUD Endpoints Provided
The hobson resource creates endpoints for you like you would on a regular RESTful API.
ID | Method | Endpoint | Example |
---|---|---|---|
find |
get | /unicorns |
/unicorns?filter[color]=purple |
count |
get | /unicorns/count |
/unicorns/count?filter[color]=yellow |
findOne |
get | /unicorns/one |
/unicorns/one?include=horns |
findById |
get | /unicorns/:unicornId |
/unicorns/5a8ed7fabf4aabad60e41247 |
create |
post | /unicorns |
/unicorns |
update |
patch | /unicorns/:unicornId |
/unicorns/5a8ed7fabf4aabad60e41247 |
remove |
delete | /unicorns/:unicornId |
/unicorns/5a8ed7fabf4aabad60e41247 |
Custom Endpoints
Here is how you add custom endpoints to the resource.
File: unicorn.resource.js
const findGreenUnicons = id: 'findGreenUnicons' path: '/green' methods: 'get' handler: async console; unicornResource;
Authentication
Routes are protected by default. Provide permission functions to give access to your users.
File: unicorn.resource.js
unicornResource ;
Logic & Hooks
Provide hooks to your endpoints which will run before and after the main handler. There is also a helpful context
object which you can use to assign data to access throughout your function chain.
File: unicorn.resource.js
unicornResource ;
You can also use old express middleware too. When added, these will run before all the other functions.
File: unicorn.resource.js
unicornResource ;
Response Standards
Endpoints should return information in a specific format so that it is easy to read on the client.
The following standards are inspired by the work done on JSend. See there standards here.
Success
Failed
Error
Maintainers
License
MIT