The Basic REST API Approach
The Adaptive Planning API has three general areas:
Metadata Retrieval and Manipulation
A client can invoke an API call by sending an HTTP POST request to the main Adaptive Planning web services endpoint. The endpoint has appended to it a version number indicating which version of the API is being invoked. The current version of the Adaptive Planning API is v25:
API Versions are generally updated when new releases of Adaptive Planning products are published, though not all releases of products will result in a new API Version. The current version will continue to be supported for at least one year after the release of the subsequent version of the API.
To see a history of API changes, see API changes by release.
The HTTP POST request will contain post data, which itself will be an XML document. This XML document contains some standard sections that are present on every API method call and some other sections that are specific to each API method call. The Adaptive Planning server will process the API method call and return the results as another XML document. Like the request, the response XML document has some sections that are the same for each API method and some sections that are specific for each API method.
All data retrieval is done in the form of a “search.” The caller specifies some criteria to match some number of elements, and the server responds with a list of metadata entities or data that match those criteria. Data creation and updating is done in the form of a bulk upload of data, also submitted via a POST directive.
All API requests are stateless, single-action requests. The user must be authenticated on each separate invocation, so there is no possibility of an intruder attempting to hijack any existing web service session.
All API requests are encrypted, as they are required to be performed using the https web protocol. The authentication credentials of the user performing the action are transmitted to Adaptive Planning as part of the body of the web services request. This means that a user's login ID and password are encrypted by the web layer before they leave the computer generating the web services request, and are only decrypted once received by the target server.
Authenticating a user in an API request does not create a persistent session for this user – each separate web service call must authenticate its user separately.
Permissions and Data Access Control
There is no special permission required for a user to be able to access web services. However, the user making the web service request must have the required permissions to actually perform the action being requested. For example, to call the importData web service method, a user must have the Import permission.
In addition, the web service methods restrict the output of each call to the set of data visible to the user making the request. For example, the exportData web service method limits the data returned to the data found on the set of levels owned by the calling user.