Skip to content

Ribbon2 REST API

Jump to bottom
Stanislav Nepochatov edited this page Oct 21, 2024 · 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;
  • PROPERTY_TYPE_NOT_FOUND - property type not found or not registered, status code - 404;
  • IO_SCHEME_NOT_FOUND - IO scheme not found, status code - 404;
  • IO_SCHEME_CONFIG_ERROR - incorrect config for IO scheme. Depends on protocol and type of scheme. Status code - 404;

Auth

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.

Get current account

Method: GET {apiUrl}/api/account
Response:

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

Users

Create user

Method: POST /api/user
Payload:

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

Hint: only existing group will be linked.
Response: same payload with initiated id value and without password field.
Errors: ACCESS_DENIED if user doesn't belongs to admin group.

Edit user

Method: PUT /api/user
Payload:

{
    "id": "100",
    "login": "user",
    "password": "NewRawPassword",
    "firstName": "Test",
    "lastName": "User",
    "description": "Normal user",
    "email": "[email protected]",
    "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 - specified incorrect id;
  • ACCESS_DENIED - user doesn't belongs to admin group;

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 - specified incorrect id;
  • ACCESS_DENIED - user doesn't belongs to admin group;

Get users page

Method: GET /api/user
Params: see query params for paginated API above.
Response: see example of response above.
Errors: ACCESS_DENIED if user doesn't belongs to admin group.

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 - specified incorrect id;
  • ACCESS_DENIED - user doesn't belongs to admin group;

Groups

Create group

Method: POST /api/group
Payload:

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

Response: same payload with initiated id.
Errors: ACCESS_DENIED if user doesn't belongs to admin group.

Edit group

Method: PUT /api/group
Payload:

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

Response: same payload.
Errors: ACCESS_DENIED if user doesn't belongs to admin group.

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 - specified incorrect id;
  • ACCESS_DENIED - user doesn't belongs to admin group;

Get groups page

Method: GET /api/group
Params: see query params for paginated API above.
Response: see example of response above.
Errors: ACCESS_DENIED if user doesn't belongs to admin group.

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 - specified incorrect id;
  • ACCESS_DENIED - user doesn't belongs to admin group;

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.
Errors: ACCESS_DENIED if user doesn't have permission to create such directory.

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 - specified incorrect full name;
  • ACCESS_DENIED - user doesn't have permission to edit directory;

Delete directory

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 - specified incorrect full name;
  • ACCESS_DENIED - user doesn't have permission to delete directory;

Get directory access permissions

Method: GET /api/directory/access/permission/all
Response:

[
    {
        "tag": "directory",
        "key": "canCreateDir",
        "description": "Allows user to create child directory",
        "defaultValue": false
    },
    {
        "tag": "directory",
        "key": "canUpdateDir",
        "description": "Allows user to update current or child directory",
        "defaultValue": false
    },
    {
        "tag": "directory",
        "key": "canEditDirAccess",
        "description": "Allows user to change access control list on directory",
        "defaultValue": false
    }
]

Get all directories permissions

Method: GET /api/directory/access/permission/all
Response:

[
    {
        "key": "canCreateMessage",
        "description": "Allows user to create message",
        "defaultValue": false,
        "tag": "message"
    },
    {
        "key": "canReadMessage",
        "description": "Allows user to read message",
        "defaultValue": true,
        "tag": "message"
    }
]

Get directory access

Method: GET /api/directory/access/:path
Path variables: :path as full name of directory to get access from.
Restrictions: user should have permission canEditAccessDir on current directory.
Response:

[
   {
      "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
      }
   }
]

Errors:

  • DIRECTORY_NOT_FOUND - specified incorrect path;
  • ACCESS_DENIED - user doesn't have permission to edit directory access;

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;
  • ACCESS_DENIED - user doesn't have permission to edit directory access;

Get permission availabie to current user by directory

Method: GET /api/directory/access/permission/current/:path
Path variables: :path as full name of directory to get permissions.
Hint: if specified directory doesn't contain any access entries, parent directory will be checked.
Response:

[
    "canCreateDir",
    "canCreateMessage"
]

Errors:

  • DIRECTORY_NOT_FOUND - specified incorrect path;
  • USER_NOT_FOUND - specified user not present;

Get directories by permission for current user

Method: GET /api/directory/permission/:permission
Path variables: :permission as name of permission to check access to.
Response: see example of respose above.
Errors:

  • USER_NOT_FOUND - specified user not present;
  • PERMISSION_NOT_FOUND - specified permission not present;

Get directories page

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

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

Create message

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

{
    "directories": ["System.Test"],
    "header": "New message",
    "parentUid": "cbd92252-a18c-4f5d-ad89-6a551f7ee2df",
    "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",
    "parentUid": "cbd92252-a18c-4f5d-ad89-6a551f7ee2df",
    "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_DIRECTORIES_REQUIRED - directories array is empty;
  • MESSAGE_NOT_FOUND - message specified in parentUid field doesn't exist;
  • ACCESS_DENIED - user doesn't have permission to create message on one of the directories;

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;
  • ACCESS_DENIED - user doesn't have permission to edit message on one of the directories;

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 - specified incorrect uid.
  • ACCESS_DENIED - user doesn't have permission to create message on one of the directories;

Get messages page

Method: GET /api/message
Params: see query params for paginated API above.
Response: see example of response above.
Errors: ACCESS_DENIED if user doesn't have permission to edit message on one of the directories.

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 - specified incorrect uid;
  • ACCESS_DENIED - user doesn't have permission to create message on one of the directories;

Get message property types

Method: GET /api/message/property/all
Response:

[
    {
        "tag": "message",
        "type": "URGENT",
        "description": "Urgent message mark."
    },
    {
        "tag": "message",
        "type": "MARK",
        "description": "User note or comment."
    },
    {
        "tag": "message",
        "type": "COPYRIGHT",
        "description": "Copyright on message content."
    },
    {
        "tag": "message",
        "type": "RELOCATED",
        "description": "Relocated from directory."
    }
]

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 - specified incorrect uid;
  • PROPERTY_TYPE_NOT_FOUND - property type not registered.

IO

Get available protocols

Method: GET /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"...]
   }
]

Errors: ACCESS_DENIED if user doesn't belongs to admin group.

Create/update scheme

Method: POST /api/io/scheme
Payload:

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

Response: same scheme payload.
Errors: ACCESS_DENIED if user doesn't belongs to admin group.

Get schemes

Method: GET /api/io/scheme Response:

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

Errors: ACCESS_DENIED if user doesn't belongs to admin group.

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"
      ...
   }
}

Errors:

  • IO_SCHEME_NOT_FOUND - scheme doesn't exist;
  • ACCESS_DENIED - user doesn't belongs to admin group;

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.
Errors:

  • IO_SCHEME_NOT_FOUND - scheme doesn't exist;
  • ACCESS_DENIED - user doesn't belongs to admin group;

Get export schemes by directory

Method: GET /api/io/export/scheme/:dirName
Path variables: :dirName as directory name;
Response: see example above in getting list of schemes;

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.
Errors:

  • IO_SCHEME_NOT_FOUND - scheme doesn't exist;
  • DIRECTORY_NOT_FOUND - specified directory doesn't exist;
  • ACCESS_DENIED - user doesn't belongs to admin group;

Dismiss export scheme from directory

Method: DELETE /api/io/export/scheme/:protocol/:name/dismiss/:dir
Path variables: :protocol as protocol of scheme, :name as name of scheme and :dir as name of directory dismiss from;
Response: raw status code 200.
Errors:

  • IO_SCHEME_NOT_FOUND - scheme doesn't exist;
  • DIRECTORY_NOT_FOUND - specified directory doesn't exist;
  • ACCESS_DENIED - user doesn't belongs to admin group;
Clone this wiki locally