Skip to content

Ribbon2 REST API

Jump to bottom
Stanislav Nepochatov edited this page Oct 21, 2021 · 20 revisions

Table of contents

[[TOC]]

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.
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.
Response: see example of group model above.
Errors: GROUP_NOT_FOUND if specified incorrect id.

Directories

Operation: create directory.
Method: POST /api/directory
Restrictions: user should have permission canCreateDir on parent directory.
Payload:

{
    "fullName": "System.Test",
    "description": "Test directory"
}

Hint: system will create all parent directories if they doesn't exist. In this case permission check will be performed on last esisting directory in path.
Response: same payload with initiated id and name.

Operation: edit directory.
Method: PUT /api/direcotry
Restrictions: user should have permission canUpdateDir on current directory.
Payload:

{
    "id": "102"
    "name": "Test",
    "fullName": "System.Test",
    "description": "Test directory, new description"
}

Response: same payload.
Hint: in fact only description field can be updated.
Errors: DIRECTORY_NOT_FOUND if specified incorrect full name.

Operation: delete group.
Method: DELETE /api/direcotry/:path
Path varialbes: :path as full name of directory to delete.
Restrictions: user should have permission canDeleteDir on current directory.
Response: raw status code 200.
Errors: DIRECTORY_NOT_FOUND if specified incorrect path.

Operation: edit directory access. Method: POST /api/directory/access/:path
Path varialbes: :path as full name of directory to edit.
Restrictions: user should have permission canEditAccessDir on current directory.
Payload:

[
   {
      "name": "user",
      "type": "USER",
      "permissions": [
         "canCreateDir": true,
         "canUpdateDir": true,
         "canDeleteDir": false
      ]
   },
   {
      "name": "UserGroup",
      "type": "GROUP",
      "permissions": [
         "canCreateDir": true,
         "canUpdateDir": false,
         "canDeleteDir": false
      ]
   },
   {
      "name": null,
      "type": "ALL",
      "permissions": [
         "canCreateDir": false,
         "canUpdateDir": false,
         "canDeleteDir": false
      ]
   }
]

Response: raw status code 200.
Errors:

  • DIRECTORY_NOT_FOUND - specified incorrect path;
  • USER_NOT_FOUND - specified user not present;
  • GROUP_NOT_FOUND - specified group not present;
  • PERMISSION_NOT_FOUND - specified permission not present;
  • PERMISSION_VALIDATION_FAILED - input data of request is incorrect;

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

Operation: get directory by path.
Method: GET /api/direcotry/:path
Path varialbes: :path as full name of directory to delete.
Response: see example of group model above.
Errors: DIRECTORY_NOT_FOUND if specified incorrect path.

Messaging

Operation: create message.
Method: POST /api/message
Restrictions: user should have permission canCreateMessage on current directory.
Payload:

{
    "directories": ["System.Test"],
    "header": "New message",
    "content": "This is a new message",
    "tags": ["test", "message", "findme"],
    "properties": [
        {
            "type": "MARK",
            "content": "Received from foreign reporter AP"
        }
    ]
}

Hint: message can be added to several directories. For each of specified directory permission check will be performed.
Hint: parent message can be specified by parentUid field value. Specified UID will be checked.
Response:

{
    "id": 104,
    "uid": "b6dca352-184c-4afe-837f-8d33138d84e8",
    "createdBy": "user",
    "created": "2020-06-11T06:11:22Z",
    "directories": ["System.Test", "Edit.Tranlation"],
    "header": "New message",
    "content": "This is a new message",
    "tags": ["test", "message", "findme"],
    "properties": [
        {
            "uid": "d16108e4-76eb-44ba-b1b3-aecb78cba216",
            "type": "MARK",
            "content": "Received from foreign reporter AP",
            "created": "2020-06-11T06:11:22Z", 
            "createdBy": "user"
        }
    ]
}

Errors:

  • DIRECTORY_NOT_FOUND - incorrect directory specified;
  • MESSAGE_DIRECORIES_REQUIRED - directories array is empty;

Operation: edit message.
Method: PUT /api/message
Restrictions: user should have permission canUpdateMessage on current directory.
Payload:

{
    "id": 104,
    "uid": "b6dca352-184c-4afe-837f-8d33138d84e8",
    "createdBy": "user",
    "created": "2020-06-11T06:11:22Z",
    "directories": ["System.Test"],
    "header": "New message",
    "content": "This is a new message\nAdded to translation team.",
    "tags": ["test", "message", "findme", "transl"],
    "properties": [
        {
            "uid": "d16108e4-76eb-44ba-b1b3-aecb78cba216",
            "type": "MARK",
            "content": "Received from foreign reporter AP",
            "created": "2020-06-11T06:11:22Z", 
            "createdBy": "user"
        }
    ]
}

Response: same payload with initiated updated and updatedBy fields.
Hint: among all fields only following can be changed: content, header, directories and tags.
Hint: message properties can't be deleted, only added. Errors:

  • MESSAGE_NOT_FOUND - incorrect message uid specified;
  • DIRECTORY_NOT_FOUND - incorrect directory specified;
  • MESSAGE_DIRECORIES_REQUIRED - directories array is empty;

Operation: delete message.
Method: DELETE /api/message/:uid
Path varialbes: :uid as uid of message to delete.
Restrictions: user should have permission canDeleteMessage on current directory.
Response: raw status code 200.
Errors: MESSAGE_NOT_FOUND if specified incorrect uid.

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

Operation: get message by uid.
Method: GET /api/message/:uid
Path varialbes: :uid as uid of message to delete.
Response: see example of group model above.
Errors: MESSAGE_NOT_FOUND if specified incorrect uid.

Operation: add message property.
Method: POST /api/message/property/:uid
Payload:

    "type": "MARK",
    "content": "Example text"
}

Response:

    "uid": "d16108e4-76eb-44ba-b1b3-aecb78cba216",
    "createdBy": "user",
    "created": "2020-06-11T06:11:22Z",
    "type": "MARK",
    "content": "Example text"
}

Errors: MESSAGE_NOT_FOUND if specified incorrect uid or PROPERTY_TYPE_NOT_FOUND if property type not registered.

IO

Operation: get available protocols.
Method: GET /{apiUrl}/api/io/protocol
Response:

[
   {
      "id": "import:mail",
      "type": "IMPORT",
      "protocol": "mail",
      "requiredConfigKeys": ["mailHost", "mailUsername", "mailPassword"...]
   },
   {
      "id": "import:plain",
      "type": "IMPORT",
      "protocol": "plain",
      "requiredConfigKeys": ["path", "charset", "format"...]
   }
]

Operation: create/update scheme.
Method: POST {apiUrl}/api/io/scheme
Payload:

{
   "id": "import:mail",
   "scheme": "import-gmail",
   "config": [
      "mailHost": "imap.gmail.com", 
      "mailUsername": "username", 
      "mailPassword": "password"
      ...
   ]
}

Response: same scheme payload.

Operation: get schemes.
Method: GET /api/io/scheme Response:

[
   {
      "id": "import:mail",
      "type": "IMPORT",
      "protocol": "mail",
      "scheme": "import-gmail"
   }
]

Operation: get scheme with config.
Method: GET /api/io/scheme/:type/:protocol/:name
Path variables: :type - as type of IO, :protocol as protocol of scheme and :name as name of scheme;
Response:

{
   "id": "import:mail",
   "scheme": "import-gmail",
   "config": [
      "mailHost": "imap.gmail.com", 
      "mailUsername": "username", 
      "mailPassword": "password"
      ...
   ]
}

Operation: delete scheme.
Method: DELETE /api/io/scheme/:type/:protocol/:name
Path variables: :type - as type of IO, :protocol as protocol of scheme and :name as name of scheme;
Response: raw status code 200.

Operation: assign export scheme to directory
Method: POST /api/io/export/scheme/:protocol/:name/assign/:dir
Path variables: :protocol as protocol of scheme, :name as name of scheme and :dir as name of directory to assign;
Response: raw status code 200.

Clone this wiki locally