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');importexpress= require('express');constapp=express();/* Configure Diaspora first: create your data sources, declare your models, etc... */Diaspora.createNamedDataSource(/* ... */);Diaspora.declareModel('PhoneBook',/* ... */);// Generates the API handler classconstexpressApiGenerator=newExpressApiGenerator({models: {PhoneBook: {singular: 'PhoneBook',plural: 'PhoneBooks',middlewares: {/* ... */},},},});// Use the middleware to handle your requestsapp.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:

constexpressApiGenerator=newExpressApiGenerator({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:

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

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