Diaspora-server

A package to add RESTful APIs to Express with Diaspora

Fancy badges:

Getting started:

Installation:

In order to run Diaspora Server, you need to install both Diaspora Server & Diaspora itself

npm i diaspora-server diaspora

Configuration:

const Diaspora = require( 'diaspora' );
const DiasporaServer = require( 'diaspora-server' );
const app = require( 'express' )();

/* Configure Diaspora first: create your data sources, declare your models, etc... */
Diaspora.createNamedDataSource( /* ... */ );
Diaspora.declareModel( 'PhoneBook', /* ... */);

app.use( '/api', DiasporaServer({
	models: {
		PhoneBook: {
			singular:    'PhoneBook',
			plural:      'PhoneBooks',
			middlewares: { /* ... */ },
		},
	},
}));

In the hash models, you can select which models you want to expose. You can use regular expressions, minimatch or plain text matching:

app.use( '/api', DiasporaServer({
	models: {
		'/ab?c\\d+/': {} // Regex, will match ac1, abc1, abc09
		'Qux*':       {} // Minimatch, will match Qux, QuxFoo, etc etc
		PhoneBook:    {} // Plain text matching
	},
});

In your model configuration, you can use following middlewares:

| Action | Middleware functions (singular API) | Middleware functions (plural API) | |---------|-------------------------------------|-----------------------------------| | Insert | post, insert, insertOne | post, insert, insertMany | | Find | get, find, findOne | get, find, findMany | | Update | patch, update, updateOne | patch, update, updateMany | | Replace | put, update, replaceOne | put, update, replaceMany | | Delete | delete, deleteOne | delete, deleteMany |

Each middleware will be called as a standard Express middleware (eg with req, res & next). You can use them to customize the behavior of Diaspora Server.

Getting further:

Diaspora Server uses the same Diaspora module than your app, both sharing models & the web server.

For each requests below, the server may respond:

• 204 No Content if the operation didn't returned an entity or the set is empty.
• 400 Bad Request if the parsing of the query failed
• 404 Not Found if using singular API with ID: /api/foo/66b72592-b1e2-4229-82b2-c94b475c9135

| Action | HTTP Verb | Additionnal possible responses | |------------------|-----------|------------------------------------------------------------------------------------------------------------------------| | Insert | POST | 201 Created on success, 400 Bad request if validation failed | | Find | GET | 200 OK on success | | Update (diff) | PUT | 200 OK on success, 400 Bad request if validation failed, 405 Method Not Allowed if no where clause | | Update (replace) | PATCH | 200 OK on success, 400 Bad request if validation failed, 405 Method Not Allowed if no where clause | | Delete | DELETE | 204 No Content if no errors occured |

The documentation will be available at https://diaspora-server.ithoughts.io/

Inspired by this tutorial

Todo

• API Maps with OPTION verb
• SOAP support?