Best Practices for API 2.0

This topic contains the high-level guidance to use the business APIs efficiently.It covers guidance on using some of the key Icertis Business API features to optimize the number of calls, size of the response, and performance of the API interaction. We have provided guidance for some of the typical challenges in accessing data using APIs such as fetching data of multiple entities, fetching large number of records, excluding the columns which may not be relevant for users, and so on.

In the end, we have also provided some specific recommendations to address the performance problem in the integration of ICI and its contracting application user interface.

URL: {{baseUrl}}/{{version}}/search

An example of the Page and PageSize parameters is as follows.

URL: {{baseUrl}}/{{version}}/agreements/{{contractTypeName}}?Page=1&PageSize=10

Filtering records

Use the Filter parameter of the API to view the filtered records.

Filter: This parameter is used to get the filtered records. You can apply different types of filters to pull records from the server.

Example:

View all agreements in the Draft status.

In this example, we have used the $eq expression, which means equal. You can use multiple expressions to filter your records. To refer to the list of applicable expressions, see the Swagger documentation.

An example of using the Filter parameters is as follows:

URL: {{baseUrl}}/{{version}}/agreements/{{contractTypeName}}?Filter=Status $eq 'Draft'

Get only the selected columns

While calling the Get API, use the Select parameter of API to get only the required properties in the response.

Select: This parameter is used to get the selected properties in the response.

Example:

For certain operations you only need the Name, Status, and SysId of the agreements. In this case, to pull only the required information, you should use the Select parameter.

Example of Select parameters is as follows:

URL: {{baseUrl}}/{{version}}/agreements/{{contractTypeName}}?Select=Name,Status,SysId

CountOnly parameter

To get the total number of rows in an entity, you can use the CountOnly parameter.

CountOnly: To get only the total rows to count.

Example:
You can use the CountOnly parameter to get the count of all agreements that have the Draft status.

URL: {{baseUrl}}/{{version}}/agreements/{{contractTypeName}}?CountOnly=true

Expand operation

Use the expand only if it is required and select the required attributes.

Example:
You want to get the Name and Status of the association of an agreement. In this case, you should only specify the Name and Status parameters in the API call as follows:

URL: {{baseUrl}}/{{version}}/agreements/{{contractTypeName}}?Expand={{level1Association}}(Select=Name,Status)