Introduction to the Asta Vision API

An API (Application Programming Interface) is a set of protocols and tools that allow different software applications to communicate with each other. APIs enable the integration of various systems, allowing them to share data and functionality seamlessly. They provide a way for different software components to interact and work together efficiently. You can think of an API as a bridge that connects two systems and lets them share data or services, in real time.

The Asta Vision API is an extra-cost addition to Asta Vision. You can use the Asta Vision API to access Asta Vision and Asta Powerproject data relating to your programmes and projects from within external applications, thereby integrating Asta Vision with any external applications that you may use. For example, you could use the Asta Vision API to integrate Asta Vision with an external field application, enabling the field application to push progress updates into your projects automatically; or you could use it to integrate Asta Vision with a Business Intelligence dashboard, refreshing the dashboard with live project information every morning.

The data you can access using the Asta Vision API includes:

  • Data on Asta Vision projects and programmes.
  • Data contained within Asta Powerproject projects that are stored as Asta Vision programme revisions.

The Asta Vision API is a 'public' REST (Representational State Transfer) API, which uses standard HTTP methods and URLs to access resources.

You can use the Asta Vision API to read Asta Vision and Asta Powerproject data and to perform certain actions, such as creating new projects and accessing workflow actions. You can also use the API to temporarily lock the latest version of Asta Vision programmes in order to perform read and write operations on the Asta Powerproject data, such as adding progress to tasks.

How APIs work

APIs operate through a request and response cycle, as explained below:

  1. API client: the client initiates communication by sending a request to the API server. This request can be triggered by user actions, such as entering a search term or clicking a button.
  2. API request: the request typically includes an endpoint (a specific URL), a method (such as GET, POST or DELETE), parameters, headers, and a request body. These components provide the necessary information for the API to process the request.
  3. API server: the server receives the request, processes it, and retrieves or manipulates the required data. It handles authentication, validates input data, and performs the necessary operations.
  4. API response: the server sends a response back to the client, which includes a status code, response headers, and a response body containing the requested data or an error message.

HTTP request methods available for use in the Asta Vision API

The following HTTP request methods are available for use in the Asta Vision API:

Use the 'GET' HTTP request method to retrieve a collection of data from a resource. For example, you could use the 'GET' method to retrieve a list of projects or a list of programmes. The 'GET' method does not change the state of any resources.

The response from a 'GET' API request includes a header that indicates the total number of items in the collection, the current page and the page size, for example:

X-Pagination-TotalCount: 100

X-Pagination-PageNumber: 1

X-Pagination-PageSize: 25

Responses of collections are paginated, with a default page size of 25 items. if you do not specify a page number in a 'GET' request, only the first page of the collection is returned.

To specify that a page other than the first should be returned, append the following query string to a 'GET' request:

“?pageNumber=<x>”

Where <x> is replaced by the number of the page you want to be returned.

Use the 'POST' HTTP request method to create or process a resource. For example, you could use the 'POST' method to create a programme, or to execute a workflow action.

Use the 'PATCH' HTTP request method to partially update a resource. For example, you could use the 'PATCH' method to update specific project or programme fields, or to update the date of a progress period.

Use the 'DELETE' HTTP request method to delete a resource. For example, you could use the 'DELETE' method to delete a link from a task.

For detailed information on how to use each of these methods on the various available resources, and to construct API requests, refer to the API Portal.

Examples of what you can do using the Asta Vision API

The following examples give some idea of the types of thing you can do using the Asta Vision API:

  • Projects and programmes - create and query projects; access programme details; download full project files and baselines.
  • Workflows - trigger and track workflow actions, for example, project approvals or check-ins.
  • Project locking and version control - lock programmes before reading and writing their data; unlock programmes while optionally creating a new version that incorporates any changes you have made.
  • Tasks and charts - retrieve and update tasks, milestones, links, constraints, float and progress.
  • Progress periods - manage and query reporting periods.
  • Code libraries - access and manage code libraries and the codes that are assigned to tasks.
  • Calendars and exceptions - query calendars, exceptions and work patterns.

Related Topics:

Using the API Portal to learn about and construct API requests

Creating access keys for the Asta Vision API

Using the Asta Vision API to lock and unlock programmes