Explorer

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 Enabling the Expose Display Name will display the name as shown in the image below. Disabling the Expose Display Name will display the name with the ID as shown below.  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. 

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 Enabling the Expose Display Name will display the name as shown in the image below. Disabling the Expose Display Name will display the name with the ID as shown below.  Fields - Choose the specific fields for the request body 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  Fields - Choose the specific fields for the request body 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

An asterisk(*) represents a mandatory field.

Click Send to update the API