Structure of an API request

API requests must be formed to an exact specification. In Anaplan Financial Consolidation they consist of an HTTP verb, also known as method; a root URL, the API version, an API endpoint, query parameters, headers, and a request body.

For example GET https://fluenceapi-prod.fluence.app//api/v2305.1/odata/ClientSchemaTable where:

• GET is the HTTP verb/method.
• https://fluenceapi-prod.fluence.app is the root URL.
• /api/v2305.1 is the API version parameter.
• /odata/ClientSchemaTable is the endpoint, or resource path, followed by the name of the client schema table

API requests may also include header data and body data.

HTTP methods are integral to a RESTful API request. APIs use common methods like GET, POST, PUT, and DELETE. These methods let you get, add, update, and delete data through API requests to the Financial Consolidation API.

Your host name, known as the root URL, is a unique URL that represents an object, or group of data objects, accessible through HTTP. The Financial Consolidation API request has its own root URL, where the HTTP client is routed to interact with data resources.

API requests in Anaplan Financial Consolidation must declare the current /api API version as part of a valid request, immediately after the root URL. The current version of the API is 2305.1.

A resource path refers to the part of the API's endpoint URL that identifies and locates a specific resource or collection of resources. It's usually a hierarchical representation of the resource's location within the API's data model.
A resource path comprises of one or more path segments, separated by forward slashes (/). Each path segment may contain alphanumeric characters, as well as certain special characters such as hyphens (-) or underscores (_). The path segments navigate through the API's resource hierarchy and identify the target resource.

In the example below, the request's endpoint would be /odata:

GET https://fluenceapi-prod.fluence.app/api/v2305.1/odata

Anaplan Financial Consolidation currently supports these endpoints:

Query Parameters serve as criteria for filtering, sorting, and allowing API requests to retrieve specific data. You can use logical operators within the query parameters.

API query parameters are optional key-value pairs that appear after the question mark in the URL. They serve as URL extensions and help determine specific content or actions based on the delivered data. To append query parameters, use a '?' at the end of the request URL, followed by the parameter name and value.

For example, you can use a query parameter to filter the results when you retrieve data from a table.

Multiple query parameters can be added by separating them with an ampersand (&), forming a query string. Query parameters can accommodate various object types with varying lengths, including strings and numbers.

Learn more about query parameters.

Some endpoint paths contain a chain of parameters that you build step-by-step to form a request. Use the ?Page parameter to specify the query page to retrieve. Use the ?PageSize to specify how many rows to fetch for the page. For example, to get the dimension metadata and its underlying properties, you might use something like this: https://fluenceapi-prod.fluence.app/api/v2305.1/metadata/Dimensions/DataView?Page=1&PageSize=100

Request headers contain information that represent elements such as the authentication token and the account tenant. A REST header may also specify the data format of the request and response, and provides information about the request's status.

For example:

In the example above, we have three headers:

• Tenant: The tenant where your data resides.
• Content-Type: the data format sent in the request body. This case specifies that the body content is in JSON format.
• X_API_TOKEN: the value of a valid API token created by an administrator, in the form of an API key.

These headers provide essential information to the server, enabling it to process the request correctly and securely.

An API request also consists of data (referred to as the “body”) that usually works with the POST and PUT HTTP methods. The body data refers to the payload or content sent along with the request. It contains the data that needs to be transmitted to the server for processing, such as JSON, or CSV data.

For example, to add a record to a client table, the body must contain all the items in the record:

In the example above, the request is a POST method to create a new row of budget data within the Consolidation client schema table. The body data is represented in JSON format and includes information about the record. In this case, the body data reflects which member for the intersection of Account, Audit, CostCenter, Currency, DataView, Date, Entity, Intercompany, Movement, Product, Scenario, Measure, Amount, text, and Periodic_Amount will be used to create a new row in the table.

It's important to note that not all API requests require a body. For example, GET requests typically don't have a body since they retrieve data from the server rather than sending data to it. However, methods like POST and PUT often require a body to send data for creation or updating purposes.

The API response is the server's reply to the client's request. It contains the data or information requested by the client. The response is typically sent back to the client in the body of an HTTP response. The response payload can be whatever is practical.

Responses include the following elements:

• Status: shows the status of the request. It can be “success” or “error”.
• Code: shows numerical status code that represents success or failure of the request.
• Data: contains the actual data returned by the API. Data responses are typically in JSON format.

Financial Consolidation API requests return HTTP responses in the 2XX, 4XX, and 5XX categories.

• 2XX responses indicate a success with the API call.
• 4XX responses indicate an issue with the request.  Check for mandatory request parameters. Then check if the request parameters and body contain the required values and types. There should be an error message in the response body to help diagnose the error.
• 5XX responses indicate communication issues between the client and API server.

The table below displays the expected HTTP responses for the Financial Consolidation API.