DivePort Web API

DivePort Web API provides HTTP access to a number of Diver Platform functions, including, but not limited to:

  • Querying cBases, cPlans, Measure Factories

  • Browsing project files

  • Running custom dive scripts

  • Listing users (admin only)

  • Downloading project files (admin only)

Authentication

To use the API you must authenticate with an access token in either of the following ways:

  • You can authenticate on every request by passing the access token in the URL query (token=...) or an HTTP header (Authorization: Bearer ...). For single synchronous requests this is convenient because it is stateless: the client does not need to keep track of any session state. However, it is slower for multiple requests, and you cannot run asynchronous requests this way.

  • You can start a session by logging in (/api/login). That request returns a session token, which you can use instead of your access token for future requests. This is much faster for subsequent requests and it allows the use of asynchronous requests.

The session times out if it is idle for two minutes. This should not affect programs using the API, but if your program is waiting for user input, DI recommends that you periodically send a simple request (such as, /api/info) to keep the session active.

For more information about access tokens, see Workbench Help.

URL encoding

As with all HTTP requests, URLs must be properly encoded.

Spaces are not permitted and must be escaped (as %20).

Some characters are valid in URLs but have special meaning. For example, query parameters are separated by ampersands and equals signs, so values with those characters must also be escaped. To find rows where the "Customer Name" column is "A, B & C", you would use a query parameter such as filter:Customer%20Name=A,%20B%20%26%20C.

Synchronous versus asynchronous queries

For data queries, this API supports both synchronous and asynchronous modes. Requests related to asynchronous queries have /async/ in the URL path.

For synchronous requests, DivePort waits until the query is finished before responding to the HTTP request. The response contains the requested data. Synchronous requests can be performed with or without a session.

For an asynchronous request, DivePort does not wait for the query to finish. Instead it responds immediately with HTTP status code 202 ("Accepted"), and provides a jobId. You can then use the /api/async/job/{jobId} request to see the status of the query. When the query is finished, you can use /api/async/job/{jobId}/data to fetch the data. DivePort retains the dive results until the session is closed or the client calls the DELETE method on /api/async/job/{jobId}. Asynchronous requests require creating a session with /api/login.

Synchronous requests are good for individual, fast, small queries. Slow or large queries might incur a network timeout. DI recommends that you use asynchronous requests if you don't know how long the query might take. However, synchronous requests are easier to use because the client doesn't need to make multiple requests.

Clients

Many programs and libraries can be configured use the DivePort Web API. For example, Python and Linux curl.

NOTE: By default, the maximum number of retrieved records is 10,000. You can use the limit= parameter to exceed the built-in limit up to 1,000,000 records. However, for retrieving more than 1 million records from the API, you must use its pagination feature.