Understanding API terminology

Throughout this Help, the following terms are used to refer to elements of the Asta Vision API:

Term	Definition	Examples
Access key	A key, supplied as a header in HTTP requests, that enables Asta Vision users to access the Asta Vision API and to construct requests with the access rights of a specific Asta Vision user. You create API access keys within Asta Vision.	Authorization: Bearer {token} A header containing an API access key, where {<token}> is replaced by the API access key.
API	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.
API Portal	A website that you can use to learn about and construct API requests. The API Portal describes the various operations that you can use to access and edit your Asta Vision and Asta Powerproject data in an API request, and shows the various parameters that you can apply to each operation. If you use the API Portal to construct sample API requests, you can then copy and paste these into external applications or into your own code, which saves you from having to code API requests from scratch. The URL of the API Portal differs for each Asta Vision API customer.	N/A
Body	Optional data that is sent with an HTTP request, which gives information on how the request should be carried out. For example, when using a 'POST' HTTP request to create a chart within a programme, the body of the request gives details of the chart that is to be created, including the chart ID, the chart name, the ID of the chart in which the new chart is to be created and the order in which the chart should appear within its parent.	In a 'POST' HTTP request to an API that enables you to create a customer, the body might contain the following information: { "id": 123, "name": "Dominique Webb", "email": "dwebb@example.com" }
Collection	A group of similar resources. A resource is a single record; all the resources of that type is a collection.	All programmes. All tasks. All cost centres. All tasks within a specified chart. All tasks with a start date greater than or equal to a specified date.
Endpoint	The full path of an HTTP request. An endpoint is part of an operation.	https://eleco.net/astavisionapi/programmes/1234/data/tasks/4321 In this example: https://eleco.net/astavisionapi/programmes/1234/data/tasks/ is the URL of the endpoint. Note that the URL of your instance of the Asta Vision API will be different to the one given in this example. 4321 is the resource.
Header	A piece of metadata that is sent alongside an HTTP request, which tells the API server how to interpret the request, provide authentication, control caching, and pass additional information needed for the operation. Some headers are required; others are optional. All HTTP requests require an 'Authorization' API access key to be supplied as a header. For 'POST' and 'PATCH' operations that relate to Asta Powerproject data, an 'x-LockKey' header that locks or unlocks the relevant programme is required.	Authorization: Bearer {token} A header containing an API access key, where {<token}> is replaced by the API access key.
HTTP request	A message that is sent by an application to an API, asking it to do something or to provide some data. An HTTP request includes the following elements: Method - what action to perform. Endpoint - what resource you are targeting. Headers - extra information that is required, eg authentication tokens, content type and API keys. Body - optional data sent with the request.	See the entries in this table that relate to the individual elements of an HTTP request for examples.
HTTP response	A message that is sent back to an application by an API, following an HTTP request. An HTTP response includes the following elements: Status code - whether or not the HTTP request succeeded. Headers - extra information, eg the format of the response and security information. Body - the actual data that is reported by the API, for example a collection of resources, information on a specific resource, or confirmation that a resource has been created.	See the API Portal for information on the responses that can be received for each operation.
Method	The action that you want an HTTP request to perform on an endpoint, as part of an operation: GET - use to retrieve a collection of data from a resource. POST - use to create or process a resource. For example, you could use the 'POST' method to create a programme, or to execute a workflow action. PATCH - use 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. DELETE - use to delete a resource. For example, you could use the 'DELETE' method to delete a link from a task.	The following example operations each contain a different method: GET /programmes/{programmeGuid}/data/calendars Use to retrieve a collection of a programme's calendars. POST /programmes/{programmeGuid}/data/charts Use to create a chart within a programme. PATCH /programmes/{programmeGuid}/data/costcentres/{costCentreId} Use to update the details of a cost centre. DELETE /programmes/{programmeGuid}/data/costrates/{costRateId} Use to delete a cost and income rate.
Operation	A single action that the API can perform using an HTTP request - a specific action on an endpoint.	GET /programmes/{programmeGuid}/data/calendars Use to retrieve a collection of a programme's calendars. POST /programmes/{programmeGuid}/data/charts Use to create a chart within a programme. PATCH /programmes/{programmeGuid}/data/costcentres/{costCentreId} Use to update the details of a cost centre. DELETE /programmes/{programmeGuid}/data/costrates/{costRateId} Use to delete a cost and income rate.
Resource	An entity that you can use the Asta Vision API to expose and manage.	An individual programme. An individual task. An individual cost centre.
URI	Uniform Resource Identifier. A resource identifier, a route or a path structure in the API.	/programmes is the programme collection URI. It identifies the collection of all programmes. /programmes/2333 is the URI of programme 2333. It identifies an individual programme. /programmes/{programmeGUid} is the URI for the programme resource.
Webhook	An HTTP callback that allows an API to automatically send event data to another application when something happens, rather than requiring that application to repeatedly ask for updates. You can use webhooks in conjunction with the Asta Vision API to inform other systems when certain types of event occur in Asta Vision. You create webhooks within Asta Vision.	A webhook that informs another application when a programme is created. A webhook that informs another application when a workflow action is carried out. A webhook that informs another application when your Business Intelligence database is updated.