Concept: JSON Formatted APIs

Only a limited number Adaptive Planning REST APIs can use JSON format for submitting and obtaining data from Adaptive Planning. More APIs will use JSON format in future releases.

JSON Requests

Each JSON request requires a:

HTTP verb or method.

Example:

GET

PUT

, or

PATCH

URL endpoint.

Based on the location of your Adaptive Planning instance, your authorization URLs and API endpoints can vary. For more information, see Adaptive Planning Authentication URLs and IP Addresses.

Example:

HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/globosales/sheet/availability

Authorization Header

Example:

--header 'Authorization: Basic c5RldmVjQLdsb2JvLmNabTpjaGFuZ2VtZQ=='

HTTP Verbs or Methods

The available methods or verbs vary depending on service and resource:

Method	Description
GET	Retrieves a collection of data or a single object.
POST	Creates a single data instance with specified data.
PATCH	Partially updates existing data.
PUT	Updates existing data and replaces the existing data with the specified data in the request body.
DELETE	Deletes an existing data instance.

URL Endpoint

Based on the location of your Adaptive Planning instance, your authorization URLs and API endpoints can vary. For more information, see Adaptive Planning Authentication URLs and IP Addresses.

https://api.adaptiveplanning.com/rest/<service name>/<version>/<tenant>/<resource path>

service name

A component name, based on functionality like

modeling

, or

security

version

The version of the service. Current version for all services:

tenant

The tenant for this service, indicating the Adaptive Planning instance. Use

default

for the default instance of the user in the authorization.

resource path

The path to the resource, using nouns like

sheet

and

availability

. The path also supports query parameters, like:

sheetName

to specify the name of a sheet in Adaptive Planning.

columnName

to specify the name of a column in an Adaptive Planning sheet.

limit

to specify the limit of object data entries included in a single response.

offset

to specify the offset to the first object in a collection to include in the response.

Example:

https://api.adaptiveplanning.com/api/rest/modeling/v1/globosales/sheet/availability?sheetName=Expense Cube&columnName=Level&columnType=Level

Example: POST Request with JSON Body

curl --location --request POST 'https://api.adaptiveplanning.com/api/rest/modeling/v1/default/sheet/availability?sheetName=Sales Cube&columnName=account&columnType=Account' \
--header 'Authorization: Basic c5RldmVjQLdsb2JvLmNabTpjaGFuZ2VtZQ==' \
--header 'Content-Type: application/json' \
--data-raw '[
        {
            "name": "Discount Percent",
            "code": "SalesCube.DiscountPercent",
            "accountGroup": false,
            "available": true
        }
]'

Collections

Resources typically represent a collection of business objects from

Adaptive Planning

returned as a JSON collection. The collection can be used in development frameworks to build lists of the business objects. A specific object from the collection is accessed through an identifier.

The sort order of objects in a collection is set by

Adaptive Planning

, and is not configurable.

Paging of collections is controlled by 2 optional query parameters, limit and offset.

Query Parameter	Description
limit	The limit of object data entries included in a single response. The default is 20, and the maximum is 100.
offset	The offset to the first object in a collection to include in the response. The default is 0.

Sample Request with Limit and Offset

The sample retrieves a collection of user instances with the

instanceCode

GLOBO


@GET 
@PATH("/users/instances?instanceCode=GLOBO&limit=20&offset=0")  
@Produces(MediaType.APPLICATION_JSON)    
public List<User> getUsers(@PathParam("instanceCode") String instanceCode,@PathParam("limit")int limit,@PathParam("offset")int offset)

Sample Response with Limit and Offset


{
    "total": 25,
    "link": {
        "next": "https://api.adaptiveplanning.com/api/rest/security/v1/default/users/instances?instanceCode=GLOBO&offset=4&limit=2",
        "previous": "https://api.adaptiveplanning.com/api/rest/security/v1/default/users/instances?instanceCode=GLOBO&offset=0&limit=2"
    },
    "users": [
        {
            "userId": 14,
            "userGuid": "474C4F424F000000000000000100000E",
            "userName": "asiaboss@globo.com",
            "instances": [
                {
                    "code": "GLOBO",
                    "default": true
                }
            ]
        },
        {
            "userId": 21,
            "userGuid": "474C4F424F0000000000000001000015",
            "userName": "Bob@globo.com",
            "instances": [
                {
                    "code": "GLOBOSALES"
                },
                {
                    "code": "GLOBOSUB"
                },
                {
                    "code": "GLOBO",
                    "default": true
                }
            ]
        }
    ]
}
 
 
Note:
-Default offset = 0 and limit = 500

Credential Types, Authentication, and Authorization

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.

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.

The

Adaptive Planning

JSON formatted APIs supports both Basic and Token Based Authentication(TBA) methods.

Adaptive Planning

supports true REST APIs in JSON format with authorization indicated in the request header and not the request body like XML APIs. See Request and Response Message Formats and Make Adaptive Planning API Requests with Workday Credentials for XML API examples.

Basic Authentication

Basic authentication uses base64 encoded username and password in the authentication header.

Sample:

'Authorization': 'Basic <insert base64 encoded string>'

Example:

xyz@demo.com:password

encodes to

eHl6QGRlbW8uY29tOnBhc3N3b3Jk

Token Based Authentication (TBA)

If you synchronize users from Workday to Adaptive Planning, you must use must use Token Based Authentication methods. To get your token, follow the steps in Make Adaptive Planning API Requests with Workday Credentials. After obtaining your token, pass it in the header.

Sample:'Authorization': 'Bearer <insert token here>'

Example: '

Authorization: Bearer eyJjdHkiOiJ0ZXh0L3BsYWluIiwiYWxnIjoiSFMyNTYifQ.eyJsb2dpbl9pZCI6InN0ZXZlY0BheWdsb2JvLmNvbSIsIm5iZiI6MTU4NjEzMDA2NywibXVsdGlfdXNlIjoiMCIsImlzX2F1dGgiOiIxIiwiZXhwIjoxODg2MTMwMTg3LCJpYXQiOjE2MDM5NDYwMjEsImp0aSI6IjM0YzFkZDY2LTY2MTMtNDk0Ny05MjFhLTliZDQ2ZDVmZDkwNyJ9.FZnLHGQ3dNfpzvW-A9ILi53z6YLGNNI45Mlc-4NT3As'