- 13 Aug 2024
- 17 Minutes to read
- Print
- PDF
Explorer
- Updated on 13 Aug 2024
- 17 Minutes to read
- Print
- PDF
A set of architectural guidelines known as REST allow data to be sent over a standardized interface (like HTTP). REST concentrates on design guidelines for developing stateless services and does not include an extra communications layer. The resource's unique URL allows a client to access it, and a representation of the resource is returned. The client is said to transfer state with each new representation of the resource.
When using the HTTP protocol to access RESTful resources, the resource's URL acts as its resource identifier, and the standard HTTP operations that can be carried out on it are GET, PUT, and POST.
We can dynamically create any Incidents/Requests/CIs using API.
User Persona: Super Admin
Configure Explorer
1. Clickicon from the top panel.
2. Navigate to Platform Studio > API Hub > Explorer.
For more information on the below, navigate to the following links
Authentication (POST) - We can ensure secure access to APIs.
Retrieve Records (GET) - We can use the API to fetch a list of records. For example, the incident list.
Create a Record (POST) - This API is used to create new records. For example, create a new incident
Update a Record (PUT) - We can use this API to update a record. For example, update a specific incident.
Retrieve a Record (GET) - This API can be used to retrieve a specific record. For example, Incident ID XX
Upload Attachment (PATCH) - This API is used to upload and update an attachment using the PATCH method in various systems.
Get Attachment (GET) - This API is used to retrieve the properties and relationship of an attachment.
Authentication (POST)
This method ensures secure access to APIs for users other than the logged in user. It can be configured within the explorer's interface. This facility allows the restricted use of API explorer based on user persona and credentials.
The following image displays the configuration screen for Authentication. For more information on the configuration, refer to the table below.
Figure: Authentication
Field | Description |
---|---|
Authentication (POST) | |
Url | The URL to authenticate is prefilled in the field. The URL can be copied using the copy icon . |
Request Body | |
User Name | Provide the username for authentication. |
Password | Specify the password for authentication. |
Box | The payload for authentication is detailed. Use the copy icon to copy the request. |
Request Headers | |
Request Format | The request format of the REST API is provided. |
Response Format | The response format of the REST API is provided. |
Click Send and the following are the details displayed. For more information, refer to the table below.
Figure: API Response
Click Use Token button to use the token for Authentication across APIs.
The following section provide details on the API configuration. For more information refer to each of the sections below.
Retrieve Records (GET)
This method is most common API function used to retrieve data from a server. It is a read-only option and does not modify the state of information on the server.
The following image displays the configuration screen for Retrieve Records. For more information on the configuration refer to the table below.
Field | Description |
---|---|
Authentication | The authentication will be based on the following types. Logged in User - Based on the login credentials used. Generated Token - Based on the credentials used in Authentication. |
General | |
Form Type* | Choose the Form Type from the drop-down menu. For example, Transaction Form or Admin Form. |
Domain* | Select the appropriate Domain as per requirement. |
Sub Domain* | Select the appropriate Sub Domain as per requirement. |
Application * | Select the Application from which the records need to be retrieved. |
Module* | Select the appropriate Module as per the Application selected. For example: Incident, Service Request |
Tenant* | Select the appropriate Tenant from which the records are to be retrieved. |
Form Name* | Select the Form Name from which the records are to be retrieved. The forms that are created and accessible for the specific Tenant will be available. Note The forms will load based on the accesses and role template. |
Retrieve Records (GET) | The table details will auto-populate based on the form name selected. Note The URL to GET records will be based on the form name selected and will be auto populated. |
Table | The associated table selected in the Form name Note When the Form Type is selected as Designer, all the relevant Admin Forms are displayed. |
URL | The URL will auto-populate |
Query Parameters | |
Default Filter | The Tenant selected in General details will be populated in this field. It can be altered based on requirement. |
Add Filters | An additional filters can be applied here. Click Add Filter and the following screen is displayed. Here we can set the conditions based on which the Filters will apply. Fields - Choose the specific fields for the request body Value - Choose the Value from the drop-down menu. Expose Display Name - Enable/Disable the option to expose the display name. Note
Note Only two attributes can be grouped as part of the AND/OR functionality. |
Limit | The number of items displayed on the list. The minimum is set as 10 by default and maximum is 1000. |
Page Number | We can limit the page numbers or set it as per requirement. |
Response Fields | We can select the response fields based on the filter option. Click the Edit icon and the following page is displayed. Select the column to move the available fields to the selected fields. Use the single arrows to move the fields individually forward and backward . Use the double arrows to move the columns together forward or backward |
Request Headers | |
Request Format | Specifies the format for the REST request body. |
Response Format | Specifies the format for the REST response body. |
Authorization | Specifies the authorization and send the request as the current user. |
An asterisk(*) represents a mandatory field.
Click Send to update the API. The following response is generated.
Figure: Sample Request Body and Response
The following metadata is available at the end of the response body. For more information on the data, refer to the table below.
Field | Description |
---|---|
HTTP Method/URI | The URI of the request body is displayed. |
Headers | |
Accept | The format in which the request is being sent. |
Status Codes | The standard HTTP status codes are displayed to indicate whether the API request has been executed successfully or not. The following are the standard response codes:
|
Execution Time | The amount of time required for the API request to be processed is called execution time. Execution time logs can help identify performance bottlenecks, optimize code and meet API performance standards. |
Current Page | The field lists the page number of the listed data. |
Page Limit | This field shows the number of records being displayed per page. |
Is Last | The query returns true or false based on whether the displayed page is the last page. |
Total Pages | A record of the total pages with records queried by the API is displayed. |
Has Previous | The query returns false if there are no previous pages to the displayed record. If there are previous pages to display, it shows true. |
Has Next | The query returns false if there are no further pages to the displayed record. If there are further pages to display, it shows true. |
Total Records | This field displays the total records returned for the API. |
Previous page URL | The previous page URL is displayed. |
Next page URL | The next page URL is displayed. |
Create a Record (POST)
The POST method in API is one of the HTTP methods used to send data to a server to create or update a resource. It is commonly used REST APIs where the server needs to accept and process data enclosed in the body of the request.
The following image displays the configuration screen for Create a Record. For more information on the configuration refer to the table below.
Field | Description |
---|---|
Authentication | The authentication will be based on the following types. Logged in User - Based on the login credentials used. Generated Token - Based on the credentials used in Authentication. |
General | |
Form Type* | Choose the Form Type from the drop-down menu. For example, Transaction Form or Admin Form. |
Domain* | Select the appropriate Domain as per requirement. |
Sub Domain* | Select the appropriate Sub Domain as per requirement. |
Application* | Select the Application from which the records need to be retrieved. |
Module* | Select the appropriate Module as per the Application selected. For example: Incident, Service Request |
Tenant* | Select the appropriate Tenant from which the records are to be retrieved. |
Form Name* | Select the Form Name from which the records are to be retrieved. The forms that are created and accessible for the specific Tenant will be available. Note The forms will load based on the accesses and role template. |
Create a Record (POST) | |
Table* | The associated table selected in the Form name is selected. |
URL | The URL will auto-populate based on the table selected in Form Name. Note The URL to POST records will be based on the form name selected and will be auto-populated. |
Request Body | The Request body is displayed when we Add a Field with the specific values. For more information refer to Add a Field. |
Add Field | Expose Display Name - Enable/Disable the option to expose the display name. Note
Value - Choose the Value from the drop-down menu. |
Query Parameters | |
Response Fields | Choose the Value from the table selected for available fields. Click the Edit icon and the following page is displayed. Select the column to move the available fields to the selected fields. Use the single arrows to move the fields individually forward and backward . Use the double arrows to move the columns together forward or backward . |
Request Headers | |
Request Format | Specifies the format for the REST request body. |
Response Format | Specifies the format for the REST response body. |
Authorization | Specifies the authorization and send the request as the current user. |
An asterisk(*) represents a mandatory field.
Click Send to update the API
Update a Record (PUT)
One of the HTTP methods used in RESTful APIs is the PUT method. It is mostly utilized for developing new resources or updating ones that don't currently exist.
The following image displays the configuration screen for Update a Record. For more information on the configuration refer to the table below.
Field | Description |
---|---|
Authentication* | The authentication will be based on the following types. Logged in User - Based on the login credentials used. Generated Token - Based on the credentials used in Authentication. |
General | |
Form Type* | Choose the Form Type from the drop-down menu. For example, Transaction Form or Admin Form. |
Domain* | Select the appropriate Domain as per requirement. |
Sub Domain* | Select the appropriate Sub Domain as per requirement. |
Application* | Select the Application from which the records need to be retrieved. |
Module* | Select the appropriate Module as per the Application selected. For example: Incident, Service Request |
Tenant | Select the appropriate Tenant from which the records are to be retrieved. |
Form Name* | Select the Form Name from which the records are to be retrieved. The forms that are created and accessible for the specific Tenant will be available. Note The forms will load based on the accesses and role template. |
Update a Record (PUT) | |
Table* | The associated table selected in the Form name is selected. |
URL | The URL will auto-populate based on the table selected in Form Name. Note The URL to PUT records will be based on the form name selected and will be auto-populated. |
Request Body | The Request body is displayed when we Add a Field with the specific values. For more information refer to Add a Field. |
Add Field | Expose Display Name - Disable to option to not expose display name. Note Enabling the option will display the name of the Value - Choose the Value from the drop-down menu. |
Query Parameters | |
Response Fields | Choose the Value from the table selected for available fields. Click the Edit icon and the following page is displayed. Select the column to move the available fields to the selected fields. Use the single arrows to move the fields individually forward and backward . Use the double arrows to move the columns together forward or backward |
Auto Id * | Enter the ID for updating the records. Note The ID depends on the selected form and will change for each module. |
Request Headers | |
Request Format | Specifies the format for the REST request body. |
Response Format | Specifies the format for the REST response body. |
Authorization | Specifies the authorization and send the request as the current user. |
An asterisk(*) represents a mandatory field.
Click Send to update the API
Retrieve a Record (GET)
The GET method is essential for retrieving records in an API. This method is most common API function used to retrieve data from a server. It is a read-only option and does not modify the state of information on the server.
The following image displays the configuration screen for Retrieve a Record. For more information on the configuration refer to the table below.
Field | Description |
---|---|
Authentication* | The authentication will be based on the following types. Logged in User - Based on the login credentials used. Generated Token - Based on the credentials used in Authentication. |
General | |
Form Type* | Choose the Form Type from the drop-down menu. For example, Transaction Form or Admin Form. |
Domain* | Select the appropriate Domain as per requirement. |
Sub Domain* | Select the appropriate Sub Domain as per requirement. |
Application* | Select the Application from which the records need to be retrieved. |
Module* | Select the appropriate Module as per the Application selected. For example, Incident, Service Request |
Tenant* | Select the appropriate Tenant from which the records are to be retrieved. |
Form Name* | Select the Form Name from which the records are to be retrieved. The forms that are created and accessible for the specific Tenant will be available. Note The forms will load based on the accesses and role template. |
Retrieve a Record (GET) | |
Table* | The associated table selected in the Form name is selected. |
URL | The URL will auto-populate based on the table selected in Form Name. Note The URL to GET records will be based on the form name selected and will be auto-populated. |
Query Parameters | |
Response Fields | Choose the Value from the table selected for available fields. Click the Edit icon and the following page is displayed. Select the column to move the available fields to the selected fields. Use the single arrows to move the fields individually forward and backward . Use the double arrows to move the columns together forward or backward . |
Auto Id* | Enter the ID for retrieving the records. Note The ID depends on the selected form and will change for each module. |
Request Headers | |
Request Format | Specifies the format for the REST request body. |
Response Format | Specifies the format for the REST response body. |
Authorization | Specifies the authorization and send the request as the current user. |
An asterisk(*) represents a mandatory field.
Click Send to update the API
Upload Attachment (PATCH)
The PATCH method is essential for file upload as an attachment. This method involves, setting up the server to handle file uploads, defining the appropriate PATCH route, and ensuring that files are sent properly.
The following image displays the configuration screen for Upload Attachment. For more information on the configuration refer to the table below.
Figure: Upload Attachment
Field | Description |
---|---|
Authentication | The authentication will be based on the following types. Logged in User - Based on the login credentials used. Generated Token - Based on the credentials used in Authentication. |
General | |
Form Type* | Choose the Form Type from the drop-down menu. For example, Transaction Form or Admin Form. |
Domain* | Select the appropriate Domain as per requirement. |
Sub Domain* | Select the appropriate Sub Domain as per requirement. |
Application* | Select the Application from which the records need to be retrieved. |
Module* | Select the appropriate Module as per the Application selected. For example: Incident, Service Request |
Tenant* | Select the appropriate Tenant from which the records are to be retrieved. |
Form Name* | Select the Form Name from which the records are to be retrieved. The forms that are created and accessible for the specific Tenant will be available. Note The forms will load based on the accesses and role template. |
Upload Attachment (PATCH) | |
Table* | The associated table selected in the Form name is selected. |
URL | The URL will auto-populate based on the table selected in Form Name. Note The URL to PATCH records will be based on the form name selected and will be auto-populated. |
Query Parameters | |
Auto Id (Ticket Id)* | Enter the Record ID for updating the records. |
Field Name* | Specify the column name for which the attachment has to be uploaded. |
File Name* | Enter the file name for the attachment. |
Request Body | |
Attachment* | Browse and upload the attachment. The uploaded attachment is displayed as shown below. Note The response is in Base 64 format. Note The attachment gets uploaded and displayed in the box below. There is an option to preview and delete the uploaded attachment. There is also an option to copy the contents displayed in the text box. |
Request Headers | |
Request Format | Specifies the format for the REST request body. |
Response Format | Specifies the format for the REST response body. |
Authorization | Specifies the authorization and send the request as the current user. |
An asterisk(*) represents a mandatory field.
Click Send to update the API.
Get Attachment (GET)
The GET method is essential for retrieving an attachment in an API. This method is most common API function used to get attachment properties such as ID, name, and content from a server by providing the necessary parameters.
The following image displays the configuration screen for Upload Attachment. For more information on the configuration refer to the table below.
Figure: Get Attachment
Field | Description |
---|---|
Authentication | The authentication will be based on the following types. Logged in User - Based on the login credentials used. Generated Token - Based on the credentials used in Authentication. |
General | |
Form Type* | Choose the Form Type from the drop-down menu. For example, Transaction Form or Admin Form. |
Domain* | Select the appropriate Domain as per requirement. |
Sub Domain* | Select the appropriate Sub Domain as per requirement. |
Application* | Select the Application from which the records need to be retrieved. |
Module* | Select the appropriate Module as per the Application selected. For example, Incident, Service Request |
Tenant* | Select the appropriate Tenant from which the records are to be retrieved. |
Form Name* | Select the Form Name from which the records are to be retrieved. The forms that are created and accessible for the specific Tenant will be available. Note The forms will load based on the accesses and role template. |
Get Attachment (GET) | |
Table* | The associated table selected in the Form name is selected. |
URL | The URL will auto-populate based on the table selected in Form Name. Note The URL to GET records will be based on the form name selected and will be auto-populated. |
Query Parameters | |
Auto Id (Incident ID)* | Enter the Incident ID for updating the records. |
Field Name* | Specify the column name for which the attachment has to be uploaded. |
File Name* | Enter the file name for the attachment. |
Attachment Type | Choose the attachment type in the response. |
Request Headers | |
Request Format | Specifies the format for the REST request body. |
Response Format | Specifies the format for the REST response body. |
Authorization | Specifies the authorization and send the request as the current user. |
An asterisk(*) represents a mandatory field.
Click Send to update the API