ARP REST API - General Info
By using the Release Planner REST API, you can rely on a robust tool for Release Planner UI development.
This topic provides information on the following:
- Overview
- General patterns of the ARP REST API
- Common Request and Response Parameters
- Methods
- REST API Authentication
- Pagination
- Filtering
A REST API allows you to make requests for resources on a web server which, in turn, returns responses containing the requested information. Calls to REST API endpoints can be made with almost any programming language.
Unlike SOAP, REST APIs use HTTP as the transport protocol (although both server and client can be based in any language). Furthermore, a REST API does not follow a standard message format, the message specifications are only to be found in the corresponding documentation.
What can I do via REST API?
The ARP REST API allows you to:
- Create, update and delete ARP objects and their dependencies including handling of custom and dynamic properties.
- Show paged list of ARP objects and allow searching and filtering.
General patterns of the ARP REST API
- Base URL - The API is accessible via a sub-domain: http://arp/api/data/v1
- Encryption - It is recommended to use https to access the ARP API.
- API response - The API returns JSON files even if it is accessed via the browser. This eases the development process, especially in case of debugging.
- Versioning - Versions are encoded in the URL.
- Instance references - Instances are always referenced by their type and either by their name or unique id.
- HTTP method mapping - The following HTTP methods are used (for more info see Methods):
- GET
- POST
- DELETE
- Dates - Dates are always returned in UTC format.
- Endpoints - Every entity has an endpoint. Dynamic properties are embedded and do not have a separate endpoint.
- Query parameters - Any resource parameter can be used for querying by specifying it in the request URL. For more information see Common Request and Response Parameters.
-
Pagination - Collections are returned in pages by default. Clients can request records by specifying a start index and a page size. For more information see Pagination.
URIs general structure
The REST API URIs have the following structure:
https://{hostname}/{application}/api/{api_name}/{version}/{resource}.{format}
Example:
https://AWI.mycompany.com/api/callbacks/v1/myresource.json
| Segment | Description |
|---|---|
| https:// | HTTPS access to the API. |
| hostname | Hostname of the API application. |
| application | Web application hosting the API. |
| api | Fixed name after the root path of the web application in order to avoid conflicts with application routes. |
| api_name | An application may provide special purpose APIs to simplify development with the API. E.g: deployment. |
| version | Version of the API. |
| resource | The resource you make the request on. |
| format | Serialization format of the API. Currently only JSON is supported. |
Common Request and Response Parameters
Request parameters
You can add query parameters to the URIs to filter the response output.
| Name | Value | Description |
|---|---|---|
| start_at | integer | Filters by page number of the response to be displayed. For more information see: Pagination |
| max_results | integer | Sets a maximum number of results to be displayed per page (=pagesize). For more information see: Pagination |
An error message will be displayed if an unexpected query parameter is submitted.
Response parameters
- hasmore
- total
- data
- id
- name
- archived
- status
- version
- connection_url
- connection_port
Values of protected properties (both custom and dynamic) will never be exported, the properties will be contained in the response with null value. Null values for protected properties will be ignored in update operations, the original values remain unchanged. Nevertheless, setting an empty string like "password": "" will reset the value to an empty value.
Collection resources
If a resource is a collection of entities, the response shows the total number of entities:
Example:
GET / applications/98454/ components
total: in this example, the Application with ID 98454 has 3 components (total= total number of resources in the collection).
hasmore: indicates if the response contains all data in the collection. Possible values:
- true = the collection contains data which is not included in the collection.
- false = you have reached the last page.
data: objects contained in the collection.
Methods
The following methods are used for resources:
| Verb | Action |
|---|---|
| GET |
Used to get a list of resources or a single one. No data is changed with this operation.
Example:
|
| POST |
Used to add a resource or to modify an existing one.
Example:
Resources can only be added or updated by one. |
| DELETE |
Used to delete single resources. Example: DELETE / plans / ID DELETE /plans -> not allowed |
Other HTTP methods such as PATCH, PUT or HEAD are not used.
Leading and trailing spaces in the API input will be trimmed.
REST API Authentication
The REST API requires basic authentication. In order to send requests, you must enter the same credentials as to connect to an AE system on your GUI client. (CLIENT/USERNAME/DEPARTMENT) + Password.
Pagination
In ARP REST API, responses are paginated to make results easy to handle.
Pagination can be very useful when you make a request to the ARP REST API and receive a lot of results. For example, if you send a request to get all existing components, thousands of records may be retrieved.
How to set limit parameters
ARP REST API allows you to set the following limit parameters:
- start_at: Page number of the response to be displayed. (Default value is 0)
-
max_results: Maximum number of results per page. (Default value is 20)
The default value can be configured in thecustomer.configfile by adding the following key:<add key="REST.DefaultPageSize" value="20" />.
The parameter "total" helps to determine how many pages the result would have.
If "start_at" or "max_results" are not set, default values will be used.
How do I know that I am on the last page?
You can see that you have reached the last page when the value of the hasmore field in the response is "false".
Filtering
You can apply filters to narrow the number of records returned.
GET requests can be filtered by the filter operator "=" (equals).
For example: GET /plans?name=Ara
See also: