User Roles

Welcome to the user roles module API specification#

This section will define APIs for the user roles feature/module. It will include API documentation for all CRUD operations involving a user role.

A single user role object, has the following keys

Key	Description	Required	Type
id	Unique identifier(Autogenerated)	Autogenerated	Number
uid	13 varying characters used for CRUD operations	NO	String(UID)
name	Defines the user roles' given name	YES	String
created	user roles' date of creation	NO	Date
lastupdated	user roles' date for when it was last updated	NO	Date

Creating a user role#

Method: POST

Creating a standalone user role#

Endpoint

/api/userRoles

Request Payload

{
    "name":"user role Name"
}

Response

These responses can vary depending on success and failure however, to here we will show the success reponse.

{
  "message": "Item successfully created",
  "payload": {
    "id": "iHWO6i7JFTI8Y",
    "created": "2021-04-26T09:06:47.990Z",
    "lastupdated": "2021-04-26T09:06:47.990Z",
    "name":"user role Name"
  }
}

Response

These responses can vary depending on success and failure however, to here we will show the success reponse.

{
  "message": "Item successfully created",
  "payload": {
    "id": "iHWO6i7JFTI8Y",
    "created": "2021-04-26T09:06:47.990Z",
    "lastupdated": "2021-04-26T09:06:47.990Z",
    "name":"user role Name"
  }
}

Get user roles#

Method: GET

Endpoint

/api/userRoles

Response

{
  "pager": {
    "page": 1,
    "pageSize": 100,
    "pageCount": 1,
    "total": 1,
    "nextPage": "/api/userRoles?page=2"
  },
  "userRoles": [
    {
      "id": "FbKroGm4tZuga",
      "created": "2021-04-26T09:36:10.740Z",
      "lastupdated": "2021-04-26T09:36:10.740Z",
      "name":"user role Name",
    }
  ]
}

Pagination and Page sizes#

You can define pages you want and the data per page size you want by passing query params in get request i.e page=2&pageSize=400
This will return data of page two with size of 400 records per page
If page and page size are not defined, the default is 1 and 100 respectively

Method: GET

Endpoint

/api/userRoles?page=3&pageSize=100

You can also pass params to get all data without pagination by passing in paging=false

Method: GET

Endpoint

/api/userRoles?paging=false

Get One user role(By ID)#

Endpoint

/api/userRoles/FbKroGm4tZuga

Response

{
  "id": "FbKroGm4tZuga",
  "created": "2021-04-26T09:36:10.740Z",
  "lastupdated": "2021-04-26T09:36:10.740Z",
  "name":"user role Name"
}

Get user roles(By Specifying fields)#

NOTE: On getting user roles, whether a single user role or the whole list, we can also specify the fields and relations we want

Endpoint

/api/userRoles?fields=id,name,parent

Response

{
  "pager": {
    "page": 1,
    "pageSize": 100,
    "pageCount": 2,
    "total": 2,
    "nextPage": "/api/userRoles?page=2"
  },
  "userRoles": [
    {
      "id": "FbKroGm4tZuga",
      "name":"user role Name"
    },
    {
      "id": "v2izbbuH5H8hI",
      "name": "Other user role",
      "parent": {
        "id": "FEpU232D9w6Lv",
        "name": "user role Parent",
        "created": "2021-06-26T19:01:00.777Z",
        "lastupdated": "2021-06-26T19:01:00.777Z"
      }
    }
  ]
}

Get user roles categories (By filtering fields)#

We can filter user roles depending on certain fields, more like a search strategy, in the example below, we will find all user roles with user role ame equal to user role Name

Endpoint

/api/userRoles?filter=name:eq:user role Name

Response

{
  "pager": {
    "page": 1,
    "pageSize": 100,
    "pageCount": 1,
    "total": 1,
    "nextPage": "/api/userRoles?page=2"
  },
  "userRoles": [
    {
      "id": "FbKroGm4tZuga",
      "created": "2021-04-26T09:36:10.740Z",
      "lastupdated": "2021-04-26T09:36:10.740Z",
      "name":"user role Name",
    }
  ]
}

NOTE: All filtering mechanisms, can be combined to produce a lobust search strategy

Available search and filter Operators

Operator	Types	Value Required	Description
eq	string \| boolean \| integer \| float \| enum \| collection (checks for size) \| date	true	Equality
like	string	true	Case sensitive string, match anywhere
ilike	string	true	Case insensitive string, match anywhere
in	string \| boolean \| integer \| float \| date	true	Find objects matching 1 or more values

Update a user role#

Method: PUT

Endpoint

/api/userRoles/FbKroGm4tZuga

Request Payload

{

    "name":"Erick Baney Name",
}

Response

{
  "message": "Item with id FbKroGm4tZuga updated successfully.",
  "payload": {
    "id": "FbKroGm4tZuga",
    "created": "2021-04-26T09:36:10.740Z",
    "lastupdated": "2021-04-26T09:36:10.740Z",
    "name":"Erick Baney Name"
  }
}

Delete a user role#

Method: DELETE

Endpoint

/api/userRoles/D67ZA1LulF2kf

Response

{
  "message": "Object with identifier D67ZA1LulF2kf deleted successfully"
}