# Adding New APIs For Access
### Overview
Roles define the permissions of a user to perform a group of tasks. The tasks are created as API calls to do certain actions when a request for those calls is sent by the system. Access permission is grated by mapping roles with API. User assigned with the roles to provide access for the API
### Pre-requisites
Before proceeding with the configuration, make sure the following pre-requisites are met -
* Knowledge of DIGIT applications is required.
* User should be aware of transactional steps in the DIGIT application.
* Knowledge of json and how to write a json is required.
* Knowledge of MDMS is required.
* Knowledge on how to create a new API.
* APIs developed on digit follow certain conventions and principles. The aim of this document is to provide some do’s and don’ts while following those principles
* APIs path should be standardised as follows:
* **/{service}/{entity}/{version}/\_create**: This endpoint should be used to create the entity
* **/{service}/{entity}/{version}/\_update**: This endpoint should be used to edit an entity which is already existing
* **/{service}/{entity}/{version}/\_search**: This endpoint should be used to provide search on the entity based on certain criteria
* **/{service}/{entity}/{version}/\_count**: This endpoint should be provided to give a count of entities that match a given search criteria
* Always use POST for each of the endpoints
* Take most search parameters in POST body only
* For further more information about how new API is developed could be referred in this link[ API Do's and Don'ts](https://digit-discuss.atlassian.net/wiki/spaces/DD/pages/686719019/API+Do%27s+and+Don%27ts)
### Key Functionalities
* Adding New APIs(actions) and Mapping Roles with that APIs provides permission to perform certain task can be restricted based on the requirement.
### Deployment Details
* After mapping Roles with APIs, the MDMS service needs to be restarted to read the newly added data.
### Configuration Details
APIs are added in **actions-test.json** and called as action.\
In MDMS, file **actions-test.json**, under **ACCESSCONTROL-ACTIONS-TEST** folder APIs are added.
API Sample -
```
{
"tenantId": "uk",
"moduleName": "ACCESSCONTROL-ACTIONS-TEST",
"actions-test": [
{
"id": ,
"name": "rainmaker-common-propertytax",
"url": "card",
"displayName": "Property Tax",
"orderNumber": 2,
"parentModule": "",
"enabled": true,
"serviceCode": "",
"code": "",
"path": "",
"navigationURL": "property-tax",
"leftIcon": "action:store",
"rightIcon": "",
"queryParams": ""
},
]
}
```
APIs are added as action array element with the request url and other required details for the array "actions-test"
Each action is defined as a key-value pair:
| Sr. No. | key | Data Type | Is Mandatory? | Definition/ Description |
| ------- | ------------- | --------- | ------------- | --------------------------------------------------- |
| 1 | id | Numeric | Yes | A unique id that identifies action. |
| 2 | name | Text | No | A short narration provided to the action. |
| 3 | url | Text | Yes | It is the endpoint of API or type like url or card. |
| 4 | displayName | Text | No | It is the display name. |
| 5 | orderNumber | Numeric | Yes | A number to represent order to display in UI |
| 6 | parentModule | Text | No | Code of the service referred to as parent |
| 7 | enabled | boolean | Yes | To enable or disable display in UI. |
| 8 | serviceCode | Text | No | Code of the service to which API belongs. |
| 9 | code | Text | No | |
| 10 | path | Text | No | |
| 11 | navigationUrl | Text | Yes | Url to navigate in UI |
| 12 | leftIcon | Icon | No | |
| 13 | rightIcon | Icon | No | |
Roles are added in **roles.json**\
In MDMS, file **roles.json**, under **ACCESSCONTROL-ROLES** folder roles are added.\
More about roles can be checked in the below link:\
[Adding roles to System](https://digit-discuss.atlassian.net/wiki/spaces/DD/pages/717946899/Adding+roles+to+System)
Mapping of Roles and APIs/action is added in **roleactions.json**, under the folder\
**ACCESSCONTROL-ROLEACTIONS**.\
**Sample mapping:**
```
{
"tenantId": "uk",
"moduleName": "ACCESSCONTROL-ROLEACTIONS",
"roleactions": [
{
"rolecode": ,
"actionid": ,
"actioncode": "",
"tenantId": (like uk,pb etc)
}
]
}
```
Role and API/action mapping is added as an array element under array roleactions.\
Each mapping is defined with key-value pairs. keys are rolecode, actionid, actioncode and tenantId.
| Sr. No. | key | Is Mandatory? | Definition/ Description |
| ------- | ---------- | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 1 | rolecode | Yes | The unique code of the role which is defined in roles.json and which required mapping for API. |
| 2 | actionid | Yes | The unique id of the API/action which is defined in actions-test.json and which is required to be mapped with the role. |
| 3 | actioncode | No | The code of the API/action which is defined in actions-test.json and which is required to be mapped with the role. |
| 4 | tenantid | Yes | tenant id of state. |
### Reference Docs
#### Doc Links
| | |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **Title** | **Link** |
| Sample actions-test.json | |
| Sample roles.json | |
| Sample roleactions.json Roles APIs mapping | |
[](http://creativecommons.org/licenses/by/4.0/)All content on this page by [eGov Foundation](https://egov.org.in/) is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.digit.org/local-governance/deploy/configure-digit/configuring-digit-services/configuring-common-services/adding-new-apis-for-access.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.