Get Started With CSO OpenAPI
How to use the CSO OpenAPI.
The CSO API allows you to create, update and retrieve data in and from CSO. The setup of the API calls is part of the project to integrate CSO with a 3rd party system to allow exchange of data between the systems.
There is no technical limit neither to the number of requests sent to the CSO REST API, nor to the size of the data set to be exchanged. However, at some point, CSO or the other system will not be able to handle the requests efficiently. Good practice is to use offset and limit operators to reduce response times, or to send large amounts of data in smaller pieces.
Terminology and syntax
All API calls to
exchange data between CSO and another database are done using the https://
protocol. The data to be exchanged, the resource , is referred to by the name of the
data type or object holding it (market, event, fact sheet, etc) followed by the ID of the
particular object or dataset in CSO, if applicable, on the following
format:
https://{name_of_cso_site}/api/{resource_name}/{resource_id}
The
name of a customer CSO site would be {company_name}.cso.coupahost.com .
Note that the API call uses the ID to specify a resource, not the actual name or the object
or data set.
The API calls are written in the JSON (JavaScript Object Notation) format. This is a lightweight text-based open standard format commonly used for data transfers between systems. Despite being developed mainly for JavaScript applications, JSON is agnostic to the programming language, and parsers and other tools are available for most languages.
Authentication
Authentication for the exchange of data between the CSO server and a 3rd party server is mediated by a unique API key. The API key is generated by Coupa. It is stored in CSO and associated with an API user . The API key is included in the header of all API requests, X-CSO-API-KEY, and the Accept header need to be set with the value ‘application/json’.
Requests
Following the syntax described above, a request to the CSO API for the fields in a fact sheet with ID 342333 in the event with ID 12312224 would look like the following:
https://{name_of_cso_site}/api/events/12312224/fact-sheets/342333/fields
It may take several requests to get a particular data set, e.g. first retrieve the events to be able to get a particular event ID, then get the fact sheets in that even to get the ID of the particular fact sheet from which you need information about the fields. The external system may be able to store those ID:s, to allow access to fields and/or fact rows in one single request.
Using one of the fact fields to hold a timestamp, an update sequence number, or another type of flag, allows you to query only the new data since last update to avoid performance issues.
Request methods
GET (Read data)
The GET request queries the CSO database and return the information matching the request to the 3rd party system. The number of objects returned is limited to 250. The response can be fine tuned by adding request parameters:-
Limit: specifies the number of objects to return;
-
Offset: specifies the start position in the data set found, to return the number of rows specified by limit from there.
Example : https://{name_of_cso_site}/api/markets?offset=10&limit=5 returns the next 5 markets starting from position 10 in the list of markets found in CSO. If there are less than 15 markets, fewer or none will be returned.
PUT (Update data)
The PUT request brings data from the 3rd party system into CSO to update existing data.
Example : api/markets/{id} updates the market
with the given ID, whereas api/markets updates all markets specified (by their ID:s) in the
request body.
Updates are done in a lenient manner, i.e. if updating one resource fails, the other ones might be successful.
POST (Create or Insert data)
A POST request creates or inserts data in CSO into the resource specified. If successful, the new ID of the data/resource is returned.
DELETE (Delete data)
Deleting data is supported for some but not all resource types. It can be done on one resource at a time, or as a bulk operation. Note that the data is completely and permanently deleted and can not be recreated in CSO. In other words, use the DELETE method with great care and mindfulness.
Responses
Responses from the CSO API include a response code and a JSON body.
Code 200 is the general success indicator. POST requests also included code 201 which indicates success in creating the data asked for.
Errors result in 4xx response codes. The error is usually triggered by calls that are not supported or allowed. Requests that fail for unknown reasons return code 500. If a request fails, do not try to re-submit it – it will fail again. More details about response codes can be found here .
Although some parameters might need to be edited to avoid name collisions etc., responses from a GET request can in the majority of cases be submitted in the bodies of a PUT or POST request. In case the format for a particular data type is not known, you can hence exploit the API to provide you the correct format.
API Operators
Although CSO can handle massive amounts of data, you may only be interested in a sub-set of the data retrieved by your GET request. The CSO API supports Coupa standard API operators which allows you to filter out the relevant data. The operators can be combined to finetune the responses. Note that all conditions have to match to retrieve a particular object or data point.
Examples of how to use operators to filter the result
Retrieve the market with the name A, if it exists:
GET on
https://{name_of_cso_site}/api/markets?name=A
Retrieve all markets with names that contain the text ‘european’, if any.
GET on
https://{name_of_cso_site}/api/markets?name[contains]=european
Retrieve all markets with names that start with ‘FTL’, if any:
GET on
https://{name_of_cso_site}/api/markets?name[starts_with]=FTL
Retrieve all markets with names ending with ‘2018’, if any:
GET on
https://{name_of_cso_site}/api/markets?name[ends_with]=2018
Retrieve the first 50 events with names including the ‘LTL’, if any:
GET on
https://{name_of_cso_site}/api/events?limit=50&name[contains]=LTL
Documentation
The OpenAPI schema is available on all CSO sites at https://{name_of_cso_site}/openapi.html . The documentation lists the objects and data types that can be accessed (market, user, fact sheet, etc) and the requests that are allowed for each of them. Clicking a request opens a schema which describes the JSON format.
Examples for reference
Get markets
GET to https://{name_of_cso_site}/api/markets
Response code: 200
Response body:
{
"total": 70,
"markets": [
{
"id": "9219593111199654844",
"name": "Market A",
"description": "A descriptive text."
},
{
"id": "9219593111199654844",
"name": "Market B"
},
… 68 more markets.
]
}
Note that the description is left out for Market B. Empty or null values are not supposed to be sent when using JSON.
Create a Market
POST to https://{name_of_cso_site}/api/markets
Request body:
{
"name": "First Market",
"description": "Optional text that describes the market."
}
Response code: 201
Response body:
{
"result": [
{
"type": "api.post.added",
"description": "1 objects created."
}
],
"added": 1,
"markets": [
{
"id": "9219593535573352536"
}
]
}
The response body includes the id created by CSO for the new market.
Update a market
PUT to https://{name_of_cso_site}/api/markets/{market_id}
Request body:
{
"name": "First Market with updated name"
}
Response code: 200
Response body:
{
"result": [
{
"type": "api.put.updated",
"description": "1 objects updated."
}
],
"updated": 1
}
The attribute “updated” contains the number of objects updated by the PUT request.