Alinex REST Server
The REST Server is part of the Alinex Operator application and serves as the data source for the front-end applications.
1. Technologies
- Language ES6 Javascript under NodeJS
- Web server ExpressJS
- Logging with morgan
- TODO Switch to Database Redis with Node Redis driver
- TODO Security using Passport with
OAuth2 - Development using nodemon, babel, eslint
- Testing with mocha and ShouldJS
- Test Database MongoDB with mongoose driver
1.1. Configuration
The server may be configured using the environment setting. First step is to use
NODE_ENV=production
(which is done on yarn start
) changes the whole setting:
- protocol will be HTTPS
- logging will be set to Apache combined format
But you may also set the following entries separately through environment settings:
PROTOCOL
- should behttp
orhttps
HOST
- hostname on which to listen to, use '0.0.0.0' for all IPsPORT
- port to listen on (defaults to 1974)
2. REST API
In the following paragraphs some of the API calls are described with:
- Http Method
- URI
- Query Parameter (starting with '?')
- Post Parameter
- Group allowed (starting with '@')
In general GET
and HEAD
are always the same but without values in HEAD
.
General Scheme
HEAD /api/<group>/<object>/<element> // check for existence
GET /api/<group>/<object>/<element> // get object(s)/<value>
POST /api/<group>/<object>/<element> // change object(s)
PUT /api/<group>/<object>/<element> // add/replace object(s)
DELETE /api/<group>/<object>/<element> // delete object(s)
Search for objects:
HEAD /api/db/person/search/name/Hund
GET /api/db/person/search/name/Hund
GET /api/db/person/search
?status_type_id=999009&name=%Hund%
Accessing an individual object:
HEAD /api/db/person/id/12345678
GET /api/db/person/id/12345678
Change object (changes in POST-DATA):
POST /api/db/person/id/12345678
status_type_id=999020
POST /api/db/person/search/name/Hund
status_type_id=999020
POST /api/db/person/search
?status_type_id=999009&name=%Hund%
status_type_id=999020
Insert/replace/remove the object completely:
PUT /api/db/person
name=..., ...
PUT /api/db/person/id/12345678
name=..., ...
DELETE /api/db/person/id/12345678
Response
The response will always be json:
# identification
date: <Date>
uri: <String>
statusCode: <Integer>
message: <String>
If the response contains some data it will also have:
# meta information
meta:
title: <String>
description: <String>
data: HashMap cols<Object>
# content data
data: Array<Object rows>
2.1. Access Management
The rights are based on the groups in which an user is member of. It is persisted within a json file on disk.
Authentication
POST /api/access/auth/login
user=<string>, password=<string>
POST /api/access/auth/logout
User Management
GET /api/access/user @admin
?email=<string>
GET /api/access/user/<string> // nopasswd
PUT /api/access/user/<string> // register
password=<string>, email=<string>
POST /api/access/user/<string> @self, @admin
password=<string>, email=<string>
DELETE /api/access/user/<string> @self, @admin
Groups
GET /api/access/group // rights
?user=<string>
GET /api/access/group/<string> // users
PUT /api/access/group/<string> @admin // new group
DELETE /api/access/group/<string> @admin // remove group
PUT /api/access/group/<string>/member/<string> @admin
DELETE /api/access/group/<string>/member/<string> @admin
3. Module
This server may also be used as module in another project. Therefore you should import and initialize it using:
import restInit from 'alinex-rest/dist/init'
import RestServer from 'alinex-rest/dist/server'
RestServer.init({ ... }) // configure server
RestServer.start()
.then(doSomething)
4. License
(C) Copyright 2017 Alexander Schilling
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.