API Basics
This article covers basic information such as a quickstart, definitions, basic syntax, operation overview, HTTP responses, authentication and pagination.
Quickstart
Step 1: Create a client and user token in Aprimo (follow steps 1 and 2)
Step 2: Test a simple route using Postman
Definitions
Resource: An Aprimo object that encapsulates related data, e.g. Activity, Project, Task, etc.
Route: The URL specified by an API user to access Aprimo resources.
ResourceID: a unique identifier of a Resource, generally a primary key.
Basic Syntax
Routes are the URLs used to access Aprimo resources. In general, routes take the following form:
https: {domain}/api/{resourceName}/{optionalID}?{optionalparameters}
domain: this is the specific domain address of your Aprimo environment
resourceName: this is the name of the resource of interest. See chapter 4 for a list of resources. Note that all resource names are pluralized, even if only a single record is specified.
optionalParameters: A standard list of optional parameters can follow the ‘?’ symbol. See the ‘Pagination’ section in this chapter for a list of supported parameters.
Examples
GET – https://{domain}/api/activities – retrieves all Activities
GET – https://{domain}/api/activities/123 – retrieves the activity with ID = 123
GET – https://{domain}/api/activities?limit=20 – retrieves the first 20 activities
Extended Syntax
In specific cases, the syntax allows nesting of objects. These exceptions are listed under the Resources chapter of this document. For example:
GET – https://{domain}/api/digital-assets/123/versions/456 – retrieves version #456 of Digital Asset #123
Headers
Each call requires the following headers (note: see the authorization page for additional headers required when retrieving access tokens).
| Header Key Name | Value |
|---|---|
| X-Access-Token | The access token retrieved from api/oauth/create-native-token or api/token, as described on the authorization page |
| Content-Type | application/json |
| Language | This header is optional. If omitted, this defaults to en-us |
Operations
The REST API allows you to create, read, update, and delete (CRUD) Aprimo resources using standard HTTP methods. A List route is also supported on all resources. In some cases, Query, and Action operations are also possible.
CRUD Operations
| Operation | HTTP Method |
|---|---|
| Create | POST |
| Read | GET
POST (when using search parameters) |
| Update | PUT
Note: On most routes, the Update/PUT operation currently replaces the existing record, so ALL non-nullable fields must be specified on each request. If a field is missing, the API will attempt to use a default value when possible. Some Update/PUT routes support field-level updates. For these routes (identified on the Routes page), only the specific fields that should be updated need to be sent as part of the request. Any field not specifically updated will remain the same. The exception to this is collection properties (where the data elements are contained within square brackets. These properties flush-and-fill, so ALL data in the collection needs to be specified. Any data not specified will be removed from the collection. |
| Delete | DELETE |
Non-CRUD Operations
| Operation | HTTP Method |
|---|---|
| List | GET |
| Query | POST |
| Other Actions | POST |
Requests and Responses
All resources use JSON for Requests and Responses. Dates are formatted as ISO 8601 strings. For example, March 16, 2020 is represented as 2020-03-16. Please refer to https://www.iso.org/iso-8601-date-and-time-format.html for more detail.
Expected Behavior
| HTTP Method | Responses on a Specific Item | Responses on a Collection |
|---|---|---|
| POST | 201 (Created). Returns a ‘Location’ header with a link to new resource.
403 (Forbidden). If the user doesn’t have permission or access to the resource. 404 (Not Found). If the create method is not available. |
405 (Method Not Allowed). |
| GET | 200 (OK). Returns a single resource.
403 (Forbidden). If the user doesn’t have permission or access to the resource. 404 (Not Found) if the ID is not found or is invalid. |
200 (OK). Returns a list of embedded resources with paging links.
403 (Forbidden). If the user doesn’t have permission or access to the resource. |
| PUT | 200 (OK).
403 (Forbidden). If the user doesn’t have permission or access to the resource. 404 (Not Found) if the ID is not found or is invalid. |
405 (Method Not Allowed). |
| DELETE | 200 (OK).
403 (Forbidden). If the user doesn’t have permission or access to the resource. 404 (Not Found) if the ID is not found or is invalid or if delete is not available. |
405 (Method Not Allowed). |
Note: in some cases, the delete operation does a hard delete (i.e. deleting the actual record). In other cases, it does a soft delete (i.e. marking the record inactive). The type of delete performed is resource-dependent, and is designed so that removing data will not break the underlying data model.
Pagination
By default, Aprimo returns 250 items on a request. Items beyond that are not included on a standard response. To get around this and retrieve specific items, use the following pagination keywords in the optional parameters following the route (note, these keywords are only supported on selected routes that frequently include large numbers of results):
- offset
The number of the starting record to be returned in the response, starting with record 0 (zero-based indexing). For example, to request the response to begin with the 1234th Activity identified by a request of all Activities, the request would be:
GET – https://{domain}/api/activities?offset=1233 – retrieves a block of 50 Activities starting with the 1234th Activity found.
- limit
The number of items returned on a request. By default, this is 50, but this value can be overridden (up to 250). For example, to retrieve only 50 Projects. The request would be:
GET – https://{domain}/api/projects?limit=50 – retrieves the first 50 Projects found.
GET – https://{domain}/api/activities?offset=1234&limit=10 – retrieves a block of 10 Activities starting with the 1234th Activity found.
sortField and sortAscending
These keywords are used together to specify a field to sort the request by. These parameters do not affect the order results are returned in – only the order the query is sorted by. To sort by multiple properties, specify multiple properties separated by commas, where the first term is the primary sort criteria. Note that there can only be one sortAscenting value, and the same value is applied to all search properties specified. Note that not all routes support the sort parameters.
GET – https://{domain}/api/projects?sortField=title,projectID&sortAscending=true&limit=50 – sorts all Projects in the system by title then ID in ascending order, then returns the first 50 of these results. Note that this only affects the records selected. It does not guarantee that the results will be returned in sorted order.