4.4.4. Getting an Entity Instances List

Let’s suppose that the system has a sales$Order entity and we need to get a list of this entity instances. Besides, we need to get not all the records, but only 50 records, starting with the 100th one. A response must contain not only simple properties of the sales$Order entity but also an information about the order customer (a reference field named customer). Orders must be sorted by date.

A base URL for getting all instances of the sales$Order entity is as follows:

http://localhost:8080/app/rest/v2/entities/sales$Order

To implement all the conditions described above the following request parameters must be specified:

  • view - a view, that will be used for loading entities. In our case the order-edit-view contains a customer reference.

  • limit - a number of instances to be returned.

  • offset - a position of the first extracted record.

  • sort - an entity attribute name that will be used for sorting.

An OAuth token must be put in the Authorization header with the Bearer type:

Authorization: Bearer 29bc6b45-83cd-4050-8c7a-2a8a60adf251

As a result, we get the following GET request URL:

http://localhost:8080/app/rest/v2/entities/sales$Order?view=order-edit-view&limit=50&offset=100&sort=date

The response will be like this:

[
  {
    "_entityName": "sales$Order",
    "_instanceName": "00001",
    "id": "46322d73-2374-1d65-a5f2-160461da22bf",
    "date": "2016-10-31",
    "description": "Vacation order",
    "number": "00001",
    "items": [
      {
        "_entityName": "sales$OrderItem",
        "_instanceName": "Beach umbrella",
        "id": "95a04f46-af7a-a307-de4e-f2d73cfc74f7",
        "price": 23,
        "name": "Beach umbrella"
      },
      {
        "_entityName": "sales$OrderItem",
        "_instanceName": "Sun lotion",
        "id": "a2129675-d158-9e3a-5496-41bf1a315917",
        "price": 9.9,
        "name": "Sun lotion"
      }
    ],
    "customer": {
      "_entityName": "sales$Customer",
      "_instanceName": "Toby Burns",
      "id": "4aa9a9d8-01df-c8df-34c8-c385b566ea05",
      "firstName": "Toby",
      "lastName": "Burns"
    }
  },
  {
    "_entityName": "sales$Order",
    "_instanceName": "00002",
    "id": "b2ad3059-384c-3e03-b62d-b8c76621b4a8",
    "date": "2016-12-31",
    "description": "New Year party set",
    "number": "00002",
    "items": [
      {
        "_entityName": "sales$OrderItem",
        "_instanceName": "Jack Daniels",
        "id": "0c566c9d-7078-4567-a85b-c67a44f9d5fe",
        "price": 50.7,
        "name": "Jack Daniels"
      },
      {
        "_entityName": "sales$OrderItem",
        "_instanceName": "Hennessy X.O",
        "id": "c01be87b-3f91-7a86-50b5-30f2f0a49127",
        "price": 79.9,
        "name": "Hennessy X.O"
      }
    ],
    "customer": {
      "_entityName": "sales$Customer",
      "_instanceName": "Morgan Collins",
      "id": "5d111245-2ed0-abec-3bee-1a196da92e3e",
      "firstName": "Morgan",
      "lastName": "Collins"
    }
  }
]

Please note, that every entity in the response has a _entityName attribute with the entity name and an _instanceName attribute with the entity instance name.