@diaspora/plugin-server

Diaspora-server

A package to add RESTful APIs to Express with Diaspora

Fancy badges:

Getting started

Installation

In order to run this plugin, you need to install both the Diaspora Server plugin & Diaspora itself.

npm install @diaspora/plugin-server @diaspora/diaspora

Configuration

import { Diaspora } from '@diaspora/diaspora';
import { ExpressApiGenerator } from '@diaspora/plugin-server' );
import express = require( 'express' );

const app = express();

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

// Generates the API handler class
const expressApiGenerator = new ExpressApiGenerator({
	models: {
		PhoneBook: {
			singular:    'PhoneBook',
			plural:      'PhoneBooks',
			middlewares: { /* ... */ },
		},
	},
});

// Use the middleware to handle your requests
app.use( '/api', expressApiGenerator.middleware );

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

const expressApiGenerator = new ExpressApiGenerator({
	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

• SOAP support?
• Planned: GraphQL API