How do I use the API with Postman Scripts ?

This is a guide to using the postman scripts (a collection of API method calls and an environment to support the calls) that are provided to users as a primer for the API.

The scripts are compiled in a collection. It is designed to be run in the provided environment. It is important to customize the environment, and to run the collection of scripts inside the environment.

Environment

The environment includes 6 variables, two of which are managed by the system. Three of the variables must be set in order to authenticate and get a list of projects. Once the project ID is identified, it must also be set.

Configuring for initial authentication

1. APIURL - This the URL for the API. Something like https://demodata.civilpro.com.

2. username - the username for an account authorized to use the instance in (1)

3. password - the password to the account with the username in (2)

Once these environment variables are set, make sure the environment is current, and then run the method “Authentication - no project” ({{APIURL}}/api/Account/Authenticate).

IMPORTANT: When setting environment variables, make sure you update the Current Value of the variable.

This method does some important things behind the scenes that you will need to understand if you are to use the API independently of Postman.

1. The method creates a JSON object from the username and password environment variables. Please note that the password gets base64 encoded prior to transmission. This object is serialized and saved in the environment as authInfo so you can inspect it and see what it should look like. You can see the script that does this in the Pre-request script section of the Postman object for the method.

2. The authInfo variable is included as the raw body submitted and the POST request sent to the server defined in APIURL

3. The returned object is parsed, and the authentication token is extracted. This token is saved in the environment under the variable token for inspection and future requests. You can see the code for this in the ‘Tests’ section of the method in Postman.

Getting the list of projects

Once successfully authenticated, you must query the list of projects to get the ID of the project you want to connect to. You can do this by calling the ‘GetProject’ method. This will provide a list of all active projects and their IDs (ProjectId). Find the desired project and note its Id.

Authenticating against the specific project

In order to query data for a project, return to the Environment, and set the ProjectId variable to the Id from the previous step. Then run the “Authentication - project” method. This method is identical to the previous “Authentication - no project” method, except that it includes the ProjectId in its body when making the request. You can see this by inspecting the Pre-request script section.

Once executed, the token is updated so that you can access the resources of the specified project.

Running other methods

Once authenticated, any other API method can be run as long as:

1. The user account has sufficient permissions

2. The token is included as the bearer in the headers of the request.

Adopting for your own applications

The Civilpro API is a common security implementation, and most users with any API experience will be familiar with sending requests to REST service with a Bearer token. Reviewing and understanding the Postman scripts is sufficient to understanding the mechanism to successfully operate on the application. A full list of the available API methods is available on the swagger page.

https://{{APIURL}}.civilpro.com/swagger/index.html

Before proceeding to operate on the data, we strongly recommend you take the time to understand the Civil Pro query language for our GET operations. This language is developed by Devexpress, and allows movement of many data aggregations to the server. This will prevent unnecessary stress on your CivilPro instance. The documentation on forming filters, sorting, grouping, limiting data using skip and take, and aggregating is available at:

DevExtreme Angular - DataSource Properties - DevExtreme Angular Documentation 

You can see examples of the use of skip, take and filter as query parameters in the included example Postman scripts.