REST API

OpenAir REST API provides an interface for integration applications to exchange information with OpenAir.

The REST API:

• Is organized around REST.

• Uses predictable resource-oriented URLs.

• Accepts JSON-encoded request bodies.

• Returns JSON-encoded responses.

• Uses standard HTTP response codes, authentication and verbs.

The REST API lets you:

• Use CRUD (create, read, update, delete) operations on OpenAir records.

• Retrieve a list of records from a collections and use pagination.

• Filter OpenAir record collections.

The REST API is a service layer that is built on top of the business layer in OpenAir. This ensures that business rules configured for your OpenAir account are applied when an integration application interacts with your OpenAir data through OpenAir REST API. Business rules include OpenAir account configuration settings and access control mechanisms, as well as any user scripts deployed on your OpenAir account.

This guide provides a reference for using the REST API. This section provides a high level overview. Review Getting Started with the REST API for guidance about setting up and using the API. Other sections in this guide address specific conceptual topics, including Supported Resources, Methods and API Features, OAuth 2.0 Authorization and Authentication, Request Format, Response Format, Active Filter Set, Errors, API Limits, Web Services Logs and API features including Filtering, Pagination, Sorting and Referenced Objects and Expansion. The final section gives reference information about supported endpoints, methods, and resources — REST API Endpoint Reference.

You can also access the generated REST API reference documentation in OpenAPI 3.0 JSON format and use it alongside this guide. For more information, see Generated API Documentation JSON.

Important:

The REST API was introduced in the October 10, 2020 OpenAir release. It is an initial version with limited functionality.

Some optional features and application settings may not be fully supported.

The current scope of the REST API is limited to selected OpenAir modules and object types. It supports the following resources: Expense reports (including attachments), Receipts (including attachments), Projects, Job codes, Contacts. See Supported Resources, Methods and API Features.

As with any other API or platform features, it is crucial that you test integration applications leveraging the REST API extensively on a Sandbox account. Make sure your integration applications run smoothly without error on a non-production account before you implement it on your production account.

Key Concepts

OpenAir REST API is an application programming interface (API) - a set of functions and procedures that let application developers access OpenAir functionality and data within their application. The information is exchanged across the internet in a consistent format.

Note:

The REST API follows the same security best practice as OpenAir. All data is encrypted in transport using the industry standard transport layer security (TLS) protocol.

REST

Representational State Transfer (REST) refers to the architectural style used to create web services that let developers access OpenAir resources at pre-defined URLs using the HTTP protocol and perform CRUD operations (Create, Retrieve, Update, Delete) on these resources.

Resource

A resource represents OpenAir data that can be uniquely identified. Each resource has its own unique URL. When accessing the URL, information and content can be returned as a JSON-encoded string, in the case of record information, or as download file, in the case of file attachments.

In OpenAir, the most important resource is a record. Resources can be grouped into collections that each contain only one type of resources - for example, a collection of expense report records. A resource can also contain a sub-collection — for example, an expense report contains a sub-collection of receipts, with each receipt being a sub-resource. Collections are themselves resources as well.

REST API Benefits

The main benefits of REST web services include the following:

• Business Layer API — In contrast with the XML API and SOAP API, which interface with the data layer in OpenAir, the REST API interfaces with the business layer. The business logic is already applied — you do not need to replicate the business logic in your integration applications. This makes integration applications simpler and faster as it reduces the volume of data that needs to be exchanged and processed. It also ensures that behavior is consistent with the OpenAir web application and across integrated applications and that you can take advantage of new features in OpenAir when they become available or when they are enabled for your account.

• OAuth 2.0 — The REST API supports OAuth 2.0 exclusively for authentication and authorization, which is a more robust and reliable way to access data.

• JSON-encoded request bodies and responses — JSON (JavaScript Object Notation) is a lightweight data-interchange format which is self-describing and human-readable.

• Easier deployment — REST has a more flexible and lightweight architecture than SOAP, which requires heavy programming and deployment environment (C#, Java).

REST API Limitations

Consider the following information when working with the REST API.

• The REST API was introduced in the October 10, 2020 OpenAir release. It is an initial version with limited functionality. Some OpenAir features and application settings may not be fully supported. See REST API Known Limitations.

• The current scope of the REST API is limited to selected OpenAir resources. See Supported Resources, Methods and API Features.

• As with any other API or platform features, it is crucial that you test integration applications leveraging the REST API extensively on a Sandbox account. Make sure your integration applications run smoothly without error on a non-production account before you implement it on your production account.