Specifications

The communication protocol used by damas-core clients and servers is based on JSON data-interchange format over HTTP.

Set of operations

PATH	METHOD	PARAMS	RESPONSE STATUS CODE
CRUD
/api/create/	POST	JSON	201, 207, 400, 403, 409, 500
/api/read/	GET, POST	URL, JSON	200, 207, 400, 403, 404, 500
/api/update/	PUT	JSON	200, 207, 400, 403, 404, 500
/api/upsert/	POST	JSON	200, 400, 403, 500
/api/delete/	DELETE	JSON	200, 207, 400, 404, 500
AUTH (jwt extension)
/api/createToken/	POST	JSON	200
/api/signIn/	POST	FORM	200, 401, 404
/api/verify/	GET	-	200, 401
SEARCH
/api/graph/	GET	URL	200, 207, 400, 404, 500
/api/graph_backwards/	GET	URL	200, 207, 400, 404, 500
/api/graph_forwards/	GET	URL	200, 207, 400, 404, 500
/api/search/	GET	URL	200, 400, 500
/api/search_one/	GET	URL	200, 400, 500
/api/search_mongo/	POST	JSON	200, 500, 501

Details

create

Insert new element(s) in the database. The elements have an _id key being their unique string identifier in the database. This key can be specified during creation, but can't be updated afterwards without first deleting the element. If it is not provided, it will be set with a default unique identifier string. The server may add some other arbitrary keys (like author, time) at creation depending on its configuration. To create multiple elements you can provide an array of objects as input and also provide an array of strings as _id keys that will be unfolded at creation time.

HTTP Requests

POST /api/create/ application/json object or array of objects

HTTP Responses

201 Created               application/json (string or array of strings) created object(s) identifiers
207 Multi-Status          application/json (array of objects and null) some objects already exist
400 Bad Request           text/html (error message) not formatted correctly
403 Forbidden             text/html (error message) the user does not have the right permission
409 Conflict              text/html (error message) all objects already exist with these identifiers
500 Internal Server Error text/html (error message) error while accessing the database

Returns the created element's identifier or an array containing the created elements identifiers in case of a multiple creation request.

In case of a multiple element creation, the returned JSON is an array of strings ordered using the same order as the input array.

207 Multi-Status happens when some specified identifiers already exist. A null value is returned in the array at corresponding position

read

Retrieve one or more elements giving their identifier(s). In addition to the GET method, a POST method is provided to avoid the limitation of the URL length.

HTTP Requests

GET /api/read/id1,id2
POST /api/read/ application/json identifier string or array of identifier strings

The HTTP headers are often limited by HTTP servers to a maximum size. NodeJS maximum header size is 80KB. The POST method is provided to avoid this limitation in order to read large numbers of identifiers.

HTTP Responses

200 OK                    application/json (objects or array of objects) requested object(s)
207 Multi-Status          application/json (array of objects and null) some objects do not exist
400 Bad Request           text/html (error message) not formatted correctly
403 Forbidden             text/html (error message) the user does not have the right permission
404 Not Found             text/html (error message) object(s) do not exist
500 Internal Server Error text/html (error message) error while accessing the database

The requested element is returned if found. In case of a request for multiple elements, an array in same order as input is returned.

update

Add, modify and remove keys on element(s) identified by their _id key. Keys are overwritten if they exist on the server. Specifying null as value removes the key. Unspecified keys are left untouched on the server. Providing an array of objects or an array of identifiers modify multiple elements with one request.

HTTP Requests

PUT /api/update/ application/json object or array of objects

HTTP Responses

200 OK                    application/json (object or array of objects) updated object(s)
207 Multi-Status          application/json (array of objects or nulls) some objects do not exist
400 Bad Request           text/html (error message) not formatted correctly
403 Forbidden             text/html (error message) the user does not have the right permission
404 Not Found             text/html (error message) object(s) do not exist
500 Internal Server Error text/html (error message) error while accessing the database

The modified element is returned. In case of a multiple element update an array in same order as input is returned.

upsert

Create or modify existing element(s). The input can be a single object, an array, and can use arrays for _id keys (similar to update). If the element is not found in the database, it is created.

HTTP Requests

POST /api/upsert/ application/json object or array of objects

HTTP Responses

200 OK                    application/json (object or array of objects) updated/created object(s)
400 Bad Request           text/html (error message) not formatted correctly
403 Forbidden             text/html (error message) the user does not have the right permission
500 Internal Server Error text/html (error message) error while accessing the database

The input accepts arrays for _id keys, as well as values "null".

delete

Permanently remove one or more elements from the database specifying their identifier(s).

HTTP Requests

DELETE /api/delete/ application/json identifier string or array of identifier strings

HTTP Responses

200 OK                    application/json (string or array of strings) deleted identifier(s)
207 Multi-Status          application/json (array of strings or null) some objects do not exist
400 Bad Request           text/html (error message) not formatted correctly
404 Not Found             text/html (error message) object(s) do not exist
500 Internal Server Error text/html (error message) could not access the database

graph

deprecated

HTTP Requests

HTTP Responses

graph_backwards

Recursively get all source nodes and edges connected to the specified node

HTTP Requests

GET /api/graph_backwards/<depth>/<id1,id2>
POST /api/graph_backwards/<depth> application/json identifier string or array of identifier strings

The HTTP headers are often limited by HTTP servers to a maximum size. NodeJS maximum header size is 80KB. The POST method is provided to avoid this limitation in order to read large numbers of identifiers.

HTTP Responses

200 OK                    application/json (array of identifiers) identifiers of the connected object(s) in the requested graph
207 Multi-Status          application/json (array of identifiers and null) some objects do not exist
400 Bad Request           text/html (error message) not formatted correctly
403 Forbidden             text/html (error message) the user does not have the right permission
404 Not Found             text/html (error message) object(s) do not exist
500 Internal Server Error text/html (error message) error while accessing the database

graph_forwards

Recursively get all target nodes and edges connected to the specified node

HTTP Requests

GET /api/graph_forwards/<depth>/<id1,id2>
POST /api/graph_forwards/<depth> application/json identifier string or array of identifier strings

The HTTP headers are often limited by HTTP servers to a maximum size. NodeJS maximum header size is 80KB. The POST method is provided to avoid this limitation in order to read large numbers of identifiers.

HTTP Responses

200 OK                    application/json (array of identifiers) identifiers of the connected object(s) in the requested graph
207 Multi-Status          application/json (array of identifiers and null) some objects do not exist
400 Bad Request           text/html (error message) not formatted correctly
403 Forbidden             text/html (error message) the user does not have the right permission
404 Not Found             text/html (error message) object(s) do not exist
500 Internal Server Error text/html (error message) error while accessing the database

search_one

HTTP Requests

GET /api/search_one/ query

HTTP Responses

200 OK                    application/json (object or null)
400 Bad Request           text/html error message
409 Conflict              text/html error message
500 Internal Server Error text/html (error message) could not access the database

search_mongo

HTTP Requests

POST /api/search_mongo application/json query sort limit skip

HTTP Responses

200 OK                    application/json (array of string identifiers)
409 Conflict              text/html error message
500 Internal Server Error text/html (error message) could not access the database
501 Not Implemented       text/html (error message) the operation is not available

createToken

Request a new token from the server, while being already authenticated

HTTP Requests

documentation needed

HTTP Responses

documentation needed

signIn

Request a token from the server, providing a username and password

HTTP Requests

POST /api/signIn/ application/x-www-form-urlencoded username password lifespan

HTTP Responses

200 Ok             application/json (object)
401 Unauthorized   text/html error message
404 Not Found      text/html error message

404 error code is return if no authentication is required.

verify

Check if the user has a token

HTTP Requests

GET /api/verify/

HTTP Responses

200 OK             application/json  (the authenticated user object)
401 Unauthorized   text/html error message