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