REST API

The resources in this API use JSON-formatted OData as the default REST protocol for accessing data. Other Web service formats are supported, including OData (Atom), SOAP, HTML, and CSV.

Resources

Resources are endpoints that are typically a collection of items. Resources can be accessed using the following HTTP methods:

GET

An HTTP GET request can be used to retrieve data from the specified resource. If the resource is a collection of objects, the GET request can be used to retrieve a specific object or the entire collection of objects from the server.

POST

An HTTP POST request can be used to create a new object in the resource. The request must contain information about the entity being created. This method is not available for resources that are not a collection of objects.

PUT

An HTTP PUT request can be used to update a resource.

DELETE

An HTTP DELETE request can be used to delete a resource. This method is not available for resources that are not a collection of objects.

Actions

Actions can be used to extend the set of operations on resources or can be used to execute unrelated actions on the server.

Typical Server Responses

200 OK The request was processed by the server without error.
201 Created The request was successful and the specified resource was created by the server.
204 No Content A request returns this status if the requested resource has a null value or the service applies a return=minimal preference.
400 Bad Request The request was not understood or was missing required parameters.
401 Unauthorized The user was not authenticated or authorized to access this resource.
403 Forbidden Access is denied to this resource.
404 Not Found This response indicates the resource does not exist.
405 Method Not Allowed The HTTP method specified is not allowed to this resource.
501 Not Implemented The server does not support the functionality required to fulfill the request.

Authentication

Authtokens are unique identifiers that users authenticate to APIs with. To use an authtoken, log in as an administrator and then click User Management. In this section, you can manage users' permissions and authtokens. You can also restrict access of APIs to specific IP addresses.

To call the API, you can specify the authtoken a number of ways.

Basic Authentication

The user's authtoken should be used as the password when using Basic Authentication.

HTTP Header

Add the HTTP header "x-cdata-authtoken" with the desired authtoken as part of the HTTP request.

Query String Parameter

Specify the authtoken as "@authtoken" as part of HTTP form-post data or a query parameter.

Additional Output Formats

In addition to the default JSON OData format that all API resources and actions support, the following Web service formats are supported in all APIs. The Input column describes the additional inputs required to request the specific format.

Format Input Description
OData (Atom) $format=Atom An alternative XML item encoding for OData.
JSONP $callback=MyCallback Output is converted into JSONP format for use in browser scripts.
RSS @RSS Normal XML RSS 2.0 encoding, automatically formatted by many browsers.
SOAP @WSDL Another XML item encoding format similar to RSS.
HTML @HTML Output is formatted as a basic HTML table.
CSV @CSV Output is converted into comma-separated values for loading into spreadsheets.
TSV @TSV Output is converted into tab-separated values for loading into spreadsheets.
CData Arc™ 2023 - 23.0.8517.0