Concept: Adaptive Planning REST API
The Basic REST API Approach
The Adaptive Planning API has 3 general areas:
- Metadata retrieval and manipulation.
- Data retrieval.
- Data creation and updating.
A client invokes an API call by sending an HTTP POST request to the main Adaptive Planning web services endpoint. The endpoint includes a version number that indicates the API version in use. The current version of the Adaptive Planning API is v40. If your instance uses non-US based, regional authentication, your authorization URLs and API endpoints vary by region. See Reference: Regional Authentication URLs.
https://api.adaptiveplanning.com/api/v40
API versions generally update with new Adaptive Planning product releases, though not all product releases result in a new API version. Workday supports the current version for at least one year after the release of the subsequent API version.
For a history of API changes, see API Changes by Release.
The HTTP POST request contains post data in an XML document. This XML document includes standard sections present in every API method call and sections specific to each API method call. The Adaptive Planning server processes the API method call and returns the results as another XML document. Like the request, the response XML document includes sections that are the same for each API method and sections that are specific to each API method.
All data retrieval uses a search. The caller specifies criteria to match a number of elements, and the server responds with a list of metadata entities or data that match the criteria. Data creation and updating use a bulk upload of data, also submitted via a POST directive.
Security
The user must be authenticated with each separate invocation, which eliminates the possibility of an intruder hijacking a web service session.
All API requests are encrypted because they must use the HTTPS web protocol. The user's authentication credentials transmit to Adaptive Planning as part of the web services request body. This means that the web layer encrypts a user's login ID and password before they leave the computer generating the web services request and decrypts only when the target server receives them.
Authenticating a user in an API request does not create a persistent session for that user; each separate web service call must authenticate its user separately.
Permissions and Data Access Control
A user doesn't require special permission to access web services. However, the user making the web service request must have the necessary permissions to perform the requested action. Example: A user must have the Import Capabilities
permission to call the importStandardData web service method.
Additionally, the web service methods restrict the output of each call to the data set visible to the user making the request. Example: The exportData web service method limits the returned data to the data found on the levels the calling user owns.