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

Requests and Responses

All resources use JSON for Requests and Responses. Dates are formatted as ISO 8601 strings.

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 50 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:

  • 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.

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.