Frequently Asked Questions

How many endpoints does the Revel API have?

Revel Systems has close to 140 API endpoints available. The most commonly used resources include Order, Payment, OrderItem, OrderHistory, OrderAllInOne, and Product. You can browse the API documentation for information on all of the available resources and their attributes.

Do I need to pass an Object ID?

Upon creating any object, Revel will assign an object ID and a corresponding resource_uri field. This ID is an auto-incremented ID and is equivalent to a primary key. These fields should not be passed when creating objects. POST requests will not be accepted if an ID or resource_uri is passed with the request.

What are the different filtering options on the Revel API?

A variety of optional filters are available when accessing the API to limit the data returned with each call. Exact matches can be accessed by simply using an equal (=) sign, while filters can be applied by using a double-underscore (__) after specifying a field in a query-string. The filters available include the following:

Which fields can I filter on?

Only certain fields on resources are allowed to be filtered on. You can reference these fields in the ‘Filtering’ section of each resource in the general API documentation.

How do I order my results?

Results can be sorted by using the order_by parameter in the query string of an API call. For example, to filter by updated_date, the following parameter can be added:

&order_by=updated_date

Like filters, ordering options are allowed on a per-field basis of each resource. You can reference the allowed ordering fields in the ‘Ordering’ section of each resource in the general API documentation.

Which HTTP methods does the Revel API support?

Revel supports HTTP methods on a per-resource basis. These can be found in each resource’s section of the general API documentation. For example, the User resource only supports GET requests, while the Product resources supports GET, POST, PUT and PATCH requests. Please be aware that Revel does not allow DELETE requests an almost all resources.

Which response status codes should I expect from API actions?

The following table shows various status codes for different API responses. This is not a comprehensive list, but should help in determining the statuses of common requests.

Is there a way to aggregate data or retrieve totals through the Revel API?

The Revel API does not support calls to aggregate or group data.

How do I expand URI fields in a single call?

The Revel API supports expanding related URI fields in a single GET call. This functionality can be used on singly-related foreign-key relationships. For example, the OrderItem resource has a foreign-key relationship to the Order resource via the OrderItem’s order field. A regular call to the OrderItem resource returns a pointer to the order’s resource URI like so:

Request:

https://***.revelup.com/resources/OrderItem/?format=json

Response object:

{ ...,
"id": 7,
"resource_uri": "resources/OrderItem/7/",
...,
"order": "/resources/Order/4/",
...
}

Using the expand option allows the entire related object, rather than only the URI pointer, to be returned in the same call. For example:

Request:

https://***.revelup.com/resources/OrderItem/?format=json&expand={"order":1}

Response object:

{ ...,
"id": 7,
"resource_uri": "resources/OrderItem/7/",
...,
"order": {....,
"created_date": "2015-09-05T09:46:00",
"final_total": 16.31,
"id": 4,
"resource_uri": "/resources/Order/4/",
....
},
...
}

This functionality can help optimize API calls by using fewer calls to return data. Expanding is only supported one level deep.

How can I get individual objects by a resource’s ID?

There are a few different ways to filter results by a resource’s ID field. If you would like to request a single record, you can add the ID after the resource name in the URL like so:

https://***.revelup.com/resources/Payment/4/?format=json

If you would like to request multiple IDs in a single call, you can use the set option and separate IDs with semicolons. For example:

https://***.revelup.com/resources/Payment/set/4;8;23;29/?format=json

Finally, if the id field allows filtering, you can use the in filter. For example:

https://***.revelup.com/resources/Order/?format=json&id__in=4,8,23,29

How can I filter on a resource’s related fields?

To filter on a resource’s related fields, filter options can be used directly on the resource name to filter by ID. For example, to return OrderItem entries for order IDs 4, 6 and 9, the following call can be made:

https://***.revelup.com/resources/OrderItem/?format=json&order__in=4,6,9

Filters can also be used on allowed filtering fields for related resources. For example, the Order resource allows filtering by the closed field. To return OrderItem entries where all related Order entries have a closed status, the following API call can be made:

https://***.revelup.com/resources/OrderItem/?format=json&order__closed=true

How can I retrieve only targeted fields of a resource?

In order to return only certain fields with GET requests, the fields parameter can be used. For example, to only retrieve the first name, last name and email of records from the Customer resource, the following API call can be made:

https://***.revelup.com/resources/Customer/?format=json&fields=first_name,last_name

Please be aware that some fields are returned by default, even if not included in the fields parameter. Also note that the fields parameter should only be used on direct attributes of a resource, as using it on related foreign-key attributes may not return the desired results and does not provide any performance advantages.

How does the Testing Instance work?

If you have signed up on an API tier with Revel Systems, you will be provided a testing instance with a login and password. Using this, you can log in to the Revel backend system to see all of the functionality available, including the Dashboard, Reports, Product/Inventory Management, etc. You can also use the testing instance to test API calls and see how they translate to or affect data on the backend. For your convenience, sample products and orders have already been created on the testing instance.