This article is a companion to https://civilpro.zendesk.com/hc/en-us/articles/6458768023823-How-do-I-create-Custom-API-Integrations-with-CivilPro-API and provides some conceptual background to principles of the API.
The CivilPro API is used by the CivilPro web UI, so anything you can do in CivilPro web can be done via the API.
Before using the API, you must authenticate. This gives you a Bearer Token. The Bearer Token accompanies every subsequent query to the API so we can retrieve the appropriate records. You can authenticate without specifying a project, but the only purpose for this is to subsequently get a list of the projects you can use to re-authenticate - this time with the Project Id. The Bearer Token includes your UserId and ProjectId to scope requests.
Requests are Scoped To Projects
Nearly every endpoint that can be called in the CivilPro API is project-scoped. That means you will only ever get results for the project that is specified in the Bearer token that must accompany each request. The exceptions to this are generally around authentication and role configuration which are not project specific as they access system wide data.
To change projects, authenticate again to get a new Bearer Token for the new project. Or...
Because automation often requires aggregation of data across multiple projects, we do support switching projects with a URI query string parameter. You can change the context of any CivilPro query by adding qryProjectId=[ProjectId] to the query.
For example:
If you are logged into project with projectid=3 then
https://demo.civilpro.com/lots will return the lots for the logged in project.
If you specify
https://demo.civilpro.com/lots?qryProjectId=412 then you will get a list of the lots for the project with ProjectId 412.
Skip, Take, Filtering, Sorting and Grouping
We use a highly customisable and powerful query language to filter, sort and group data server-side.
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
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.
Understanding Data Shapes
What each of the data endpoints does in CivilPro, or what endpoint is useful for a given purpose may not be immediately obvious. If you are trying to find a specific endpoint, we recommend simply performing the action you want in the web UI and monitoring the requests in your browser. We use the same API you have access to, so this immediately demonstrates how we process data in any given scenario.