JSON-RPC 2.0 API
The webservice module in XELOS supports communication via JSON-RPC 2.0.
About JSON-RPC 2.0
JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format.
More information about JSON-RPC 2.0
Authorization and Access
API Access is limited to authorized accounts. The roles and rights of the used account will also reflect on the available endpoints and their functionality - e.g. an administrative account will have more API functions than a standard user account. It is advised to create specific API accounts and limit the rights to reflect the purpose for which they have been created.
Basic Authentication
The primary access method is to use a dedicated API user and use login/password as basic authentication.
Example:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
OAuth2 Authorization Code
Alternatively you can use the OAuth2 Authorization Code Flow to access the API on behalf of a user. Please configure allowed Apps in the webservice module configuration.
| Authorization/Token Endpoint | /webservice/authorize/server |
| Refresh Token Endpoint | /webservice/authorize/refresh_token |
The requested scope should be reflecting the modules you want to access separated by spaces (e.g. "crm lookbook")
Please provide the access_token as Bearer Token in the HTTP Authorization Header when accessing the API.
Example:
Authorization: Bearer <TOKEN>
Example Request/Response
Request:
curl 'https://intranet.example.org/webservice/json/useradmin' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
--data-raw '{"jsonrpc":"2.0","method":"list_users","id":1,"params":{"query":"","start":"0","limit":"1"}}'
Response:
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"total": 1,
"userList": [
{
"id": 6,
"login": "user-login",
"email": "user@example.org",
"firstname": "John",
"lastname": "Doe",
"displayname": "John Doe",
"security_group": "1",
"last_activity": "2020-01-01T05:04:10+00:00",
"status": "active",
"memo": false
}
]
}
}
Documentation and Demo
Every XELOS installation generates its own basic API reference, based on the configured modules and access rights the users has. The dynamic documentation also provides simple means to run example calls via the browser and see the result of the API.
You can find the dynamic JSON documentation at /webservice/json in your installation.
