Pyramid includes a robust library of API functions to allow customers to programmatically access and manage the application. The API's are exposed through REST and can be used from almost any programming environment that supports standard REST calls.
The REST API's come in 2 versions.
- Version 1.0 (up to 2018.04) covers core functionality - but has been deprecated. It is still included for backwards compatibility.
- Version 2.0 (from 2018.05 onwards) covers the same functionality but has been simplified and extended.
For long term stability and support, developers should be working off the 2.0 version.
Get vs POST
Classic REST APIs typically use GET templates to drive functionality. However, this approach is best suited for simplistic functions and is inherently weak when there are multiple method parameters (which is usually too long for GET URLs) and if the parameter objects are richer with multiple (nested) property options and settings.
As such, Pyramid's API is modeled on a "POST" model, where JSON data objects are posted in the API method calls facilitating the larger, more complex nested objects (in JSON). They also allow a much simpler and direct method of authorizing each method call using security tokens. Pyramid APIs are still executed via an URL model, using the same HTTP protocols and responses, with the method name driving the URL as per standard GET.
The more standardized approach to REST uses classic verb structures (Add / Edit / Delete etc) for different objects. Since the objects in Pyramid contain a significant number of properties and there are complexities around security and API operation, Pyramid has decided on a "direct method" approach to the API methods instead to simplify implementation of the API and associated activities.
The REST API functions cover a variety of core functions, covering authentication and access, administration and content operations. Where relevant, objects needed to implement these functions are described in a separate definitions list.
- Authentication Index - logging into the application programmatically
- Access Index - security and system access operations
- Content Index - content management and operations
- Query Index - query execution
- Data Sources Index - data source management and operations
- Tasks Index - task operations
- Notifications Index - notification details
API 1.0 (deprecated)
Object Definitions for both API Versions
- Object Definitions Index - all objects and classes used in the API calls and responses.
API Response Status
When an API is called a status of the call is usually given withing the response. The API documentation highlights the response of successful calls. The list of all statuses and their associated status codes, including unsuccessful calls, is provided here.
Examples are provided throughout the documentation covering a variety of the methods in the API. The methods with examples are highlighted on the main section ('namespace') pages above.