Skip to content

Ribbon2 REST API

Jump to bottom
Stanislav Nepochatov edited this page Jun 10, 2020 · 20 revisions

General

By default API returns status code and some response.

Any paginated API method supports following query params:

  • page - number of page, starting from 0. Default value 0;
  • size - number of entities in page. Default value 30;
  • orderBy - name of property to set order by. Default value id;
  • direction - direction of sorting on order by. Defaul value ASC;

Example of paginated response:

{
    "content": [...],
    "totalCount": 1000
}

Error response format:

{
    "code": "ACCESS_DENIED",
    "message": "Access denied for directory 'System.Test'"
}

where:

  • code: general code of the response (see below complete list). Default OK;
  • message: rendered messaged from server;

All errors will be returned with HTTP code above 400!

List of error codes:

  • UNREGISTERED - unregistered error code, status code - 500;
  • CALL_ERROR - underlying module call error, status code - 504;
  • ACCESS_DENIED - access denied or user haven't required permission, status code - 401;
  • USER_NOT_FOUND - required user not found, status code - 404;
  • GROUP_NOT_FOUND - required group not found, status code - 404;
  • DIRECTORY_NOT_FOUND - required directory not found, status code - 404;
  • PERMISSION_NOT_FOUND - required permission not found, status code - 404;
  • PERMISSION_VALIDATION_FAILED - permission data validation failed, status code - 400;
  • MESSAGE_NOT_FOUND - required message not found, status code - 404;
  • MESSAGE_DIRECORIES_REQUIRED - directory list in message is empty or not valid, status code - 400;

Auth

Operation: authentication.
Method: POST {apiUrl}/auth
Params: login and password.
Response: raw JWT token.
Errors: raw 403 Forbidden response in case of incorrect credentials.

Use received token in x-ribbon2-auth (name of header can be override by config, see gateway section) header to get access to secured API.

Operation: get current account.
Method: GET {apiUrl}/api/account
Response:

{
    "id": 1
    "login": "user",
    "firstName": "Test",
    "lastName": "User",
    "description": "Normal user"
    "email": "user@example.com",
    "enabled": true,
    "groups": [
        "UserGroup",
        "Editors"
    ]
}

Users

Operation: create user.
Method: POST /api/user
Payload:

{
    "login": "user",
    "password": "RawPassword"
    "firstName": "Test",
    "lastName": "User",
    "description": "Normal user"
    "email": "user@example.com",
    "enabled": true,
    "groups": [
        "UserGroup",
        "Editors"
    ]
}

Hint: only existing group will be linked.
Response: same payload with initiated id value and without password field.

Operation: edit user.
Method: PUT /api/user
Payload:

{
    "id": "100",
    "login": "user",
    "password": "NewRawPassword"
    "firstName": "Test",
    "lastName": "User",
    "description": "Normal user"
    "email": "user@example.com",
    "enabled": true,
    "groups": [
        "UserGroup",
        "Editors"
    ]
}

Hint: only existing group will be linked.
Hint: if password field were not specified on edit system will keep old password.
Response: same payload without password field.
Errors: USER_NOT_FOUND if specified incorrect id.

Operation: delete user.
Method: DELETE /api/user/:id
Path varialbes: :id as id of user to delete.
Response: raw status code 200.
Errors: USER_NOT_FOUND if specified incorrect id.

Operation: get users page.
Method: GET /api/user
Params: see query params for paginated API above.
Response: see example of response above.

Operation: get user by id.
Method: GET /api/user/:id
Path varialbes: :id as id of user to get.
Params: see query params for paginated API above.
Response: see example of user model above.
Errors: USER_NOT_FOUND if specified incorrect id.

Groups

Operation: create group.
Method: POST /api/group
Payload:

{
    "name": "UserGroup",
    "description": "Defaul user group"
}

Response: same payload with initiated id.

Operation: edit group.
Method: PUT /api/group
Payload:

{
    "id": "101"
    "name": "UserGroup",
    "description": "Defaul user group, edited"
}

Response: same payload.
Errors: GROUP_NOT_FOUND if specified incorrect id.

Operation: delete group.
Method: DELETE /api/group/:id
Path varialbes: :id as id of group to delete.
Response: raw status code 200.
Errors: GROUP_NOT_FOUND if specified incorrect id.

Operation: get groups page.
Method: GET /api/group
Params: see query params for paginated API above.
Response: see example of response above.

Operation: get group by id.
Method: GET /api/group/:id
Path varialbes: :id as id of group to get.
Params: see query params for paginated API above.
Response: see example of group model above.
Errors: GROUP_NOT_FOUND if specified incorrect id.

Directories

Get directories

Method: GET {apiUrl}/directory/tree Normal result: complete tree of directories on server:

[
    {
        "name": "System",
        "fullName": "System",
        "description": "System post directory",
        "languages": ["EN", "RU"]
        "children": [
            {
                "name": "Test",
                "fullName": "System.Test",
                "description": "Post testing directory",
                "languages": ["EN", "RU", "UA"]
            }
        ]
    }
]

Errors: AUTH_FORBIDDEN if user were not log in.

Get single directory

Method: GET {apiUrl}/directory?path={path} Params: {path} - full name (path) of directory (e.g. System.Test) Normal result:

{
    "name": "System",
    "fullName": "System",
    "description": "System post directory",
    "languages": ["EN", "RU"],
    "accessEntries": [
        {
            "key": "User1",
            "groupPermission": false,
            "permissionDescriptor": [true, false, false]
        },
        {
            "key": "Group1",
            "groupPermission": true,
            "permissionDescriptor": [true, true, false]
        },
        {
            "key": "ALL",
            "groupPermission": true,
            "permissionDescriptor": [false, false, false]
        }
    ]
}

Errors: AUTH_FORBIDDEN if user were not log in, NOT_FOUND if there is no directory with specified path.`

Create/update directory

Method: POST/PUT {apiUrl}/directory Request:

{
    "fullName": "System.Test.New",
    "description": "System post directory",
    "languages": ["EN", "RU"],
    "accessEntries": [...]
}

Errors: AUTH_FORBIDDEN if user were not log in, ACCESS_DENIED if user doesn't have permission to create directory.

Delete directory

Method: DELETE {apiUrl}/directory?path={path} Params: {path} - full name (path) of directory (e.g. System.Test) Normal result: see generic responce above; Errors: AUTH_FORBIDDEN if user were not log in, ACCESS_DENIED if user doesn't have permission to create directory, DIRECTORY_IS_NOT_EMPTY if directory contains some messages, NOT_FOUND if there is no directory with specified path.

Messaging

Post message

Method: POST {apiUrl}/message Multipart request: head with general message info, body for message body; Head:

    "parentId": "22317",
    "directories": ["System.Test"],
    "header": "Test message",
    "tags": ["test", "message", "system"],
    "language": "EN",
    "mimeType": "text/plain"
    "properties": [
        {
            "type": "COPYRIGHT",
            "value": "AP"
        },
        {
            "type": "URGENT",
            "value": "true"
        }
    ]

Response: same message structure with initiated index, date and previousAuthor fields (if previousIndex were specified). Errors: AUTH_FORBIDDEN if user were not log in, ACCESS_DENIED if user doesn't have access at least for one of the specified directories.

Edit message

Same as posting but need to specify index field in request. Body and attachment also would be edited.

Get message

Method: {apiUrl}/message?id={id} Params: {id} where index is id of message; Response: news message with body; Errors: AUTH_FORBIDDEN if user were not log in, ACCESS_DENIED if user doesn't have access at least for one of the specified directories, NOT_FOUND if message were deleted or else.

Delete message

Method: DELETE {apiUrl}/message/{id} Params: $id where index is id of message; Normal result: generic response with header of deleted message; Errors: AUTH_FORBIDDEN if user were not log in, ACCESS_DENIED if user doesn't have access at least for one of the specified directories, NOT_FOUND if message were deleted or else.

Clone this wiki locally