RestFull API

Schema

All API can be accessed over HTTP and HTTPS but it’s highly recommended to use it over HTTPS.

Server configuration

To be able to call apis you must authorise the ip from which you are calling. (As mentioned in documentation “Guide administration- Process”)
Add the following keys in Administration/server/parameters :

• com.axemble.security.ExternalAuthenticationAction.allowedAddresses=YOUR_IP (Allow call to rest api)
• com.axemble.security.Authentication.allowedAddresses.sysadmin=YOUR_IP (Allow sysadmin to connect from this ip)

Content type

All data is sent and received as JSON.

Request Accept header must be application/json and response Content-Type header is always application/json; charset=utf-8

In POST query blank fields are included as null instead of being omitted.

All timestamps request and response use ISO 8601 format : yyyy-MM-dd'T'HH:mm:ss.SSSZ

Ref representations

When you fetch object with link to another object, the link including a subset of attributes for the resource. This is the “Ref” representation of the object. (Some attributes are computationally expensive for the API to provide. For performance reasons, the Ref representation excludes those attributes. To obtain those attributes, fetch the “detailed” representation.)

Example: When you get a user, you get the ref representation of the linked organization.

HTTP verbs

Where possible, API strives to use appropriate HTTP verbs for each action.

PATCH request

PATCH request follow the RFC6902

Content type

PATCH Request Accept header must be application/json-patch+json

Document Structure

JSON Patch defines a JSON document structure for expressing a sequence of operations to apply to a JavaScript Object Notation (JSON) document; it is suitable for use with the HTTP PATCH method. The “application/json-patch+json” media type is used to identify such patch documents.

Pager

Requests that return multiple items will be paginated to 50 items on the first page by default, with a maximum up to 500 items per page. You can specify further pages with the ?range parameter, ?range=startNumberItem-itemPerPage

Example

Get the 25 first items : http://server.tld/webapp/endpoint/url?range=0-25

Get from the 26th to the 50th items : http://server.tld/webapp/endpoint/url?range=25-25

Get from the 51th to the 75th items : http://server.tld/webapp/endpoint/url?range=50-25

Sorter

Requests that return multiple items will can be sort. You can specify the attribute name for ascending sort with the ?sorter parameter, prefix the attribute name with a - for a descending sort.

example

Descending sort on name attribute : http://server.tld/webapp/endpoint/url?sorter=-name

Filters

Requests that return multiple items that can be filtered. You can specify multiple ?filters parameter, with the format : ?filters=attributeName:operator:value

Available operators

Filters mode

If multiple filters are specified, you can choose the mode to execute them with the format : ?filterMode=value

View response mode

You can choose the response mode when executing a view with the format : ?responseMode=mode

Errors by status code

Error

The following table describes the top-level JSON object attributes present in the body of 409 responses.

{
  "code": 409,
  "message": "error message summary"
}

ValidationError

The following table describes the top-level JSON object attributes present in the body of 400 responses.

This extends Error

{
	"code": 400,
	"message": "",
	"fields": [
		{
			"name": "id",
			"message": "is not a number"
		}
	]
}

PasswordError

The following table describes the top-level JSON object attributes present in the body of mismatched password complexity error.

This extends Error

	{
	"code": 400,
	"message": "Invalid password",
	"errors": [
			"length",
			"lowercase"
		]
	}

Authentication

MoovApps external authentication

You can authenticate through MoovApps external authentication.

Generate authentication token

• Request

curl --header "Content-Type: application/json" \
--request POST \
--data '{"login":"username","password":"pwd"}' \
https://server.tld/webapp/api/v2/authentication

• Response

{
	"token": "generated-token",
	"expiration": "YYYY-MM-DDTHH:MM:SSZ"
}

Call API endpoint with X-AUTHENTICATION-KEY header

During the time to live of the token you can call API endpoint with X-AUTHENTICATION-KEY header.

curl --header "Content-Type: application/json" \
--header "X-AUTHENTICATION-KEY: generated-token" \
https://server.tld/webapp/api/v2/directory/users