Retrieving resource collections¶

For retrieving collections of resources, the query string may be used to specify pagination, sorting and filtering directives.

Pagination¶

pageSize:: integer-type, the number of items in each page.
page:: integer-type, page number, index from 0.

On all list endpoints link headers can be used for pagination. For example in the customer list endpoint the following link headers are returned:

<https://api.fieldaware.net/user/?page=0&pageSize=20>; rel=first,
<https://api.fieldaware.net/user/?page=7&pageSize=20>; rel=last,
<https://api.fieldaware.net/user/?page=3&pageSize=20>; rel=next,
<https://api.fieldaware.net/user/?page=1&pageSize=20>; rel=prev,

Sorting¶

sortedBy:: string-type, an attribute name to sort by. The available options are listed for each list resource in the reference section of this document.

For example, the query parameters induce ordering by name in descending order (the minus sign).

GET /customer/?sortedBy=-name HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Accept: application/json

Filtering¶

Filters are specified as as a series of name, value pairs on the query string. For the time being only equality filtering is provided.

For example, the following query parameters restrict the locations list resource to the locations in region MA that are billing locations:

GET /location/?region=MA&isBilling=true HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Accept: application/json

Examples¶

In the following examples user retrieves customers. The GET request is presented without and with additional parameters that allow to sort, filter and page retrieved resources.

Retrieve resources without filters¶

GET /customer/¶

GET request without filters returning a list of customers

Sample request:

GET /customer/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Accept: application/json

Sample response:

Note: in the example below the list of items is shortened for illustration purposes.

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.fieldaware.net/customer/?page=0>; rel=first,
      <https://api.fieldaware.net/customer/?page=9>; rel=last,
      <https://api.fieldaware.net/customer/?page=1>; rel=next

{
  "count": 190,
  "pageSize": 20,
  "items": [
    {
      "link": {
        "url": "https://api.fieldaware.net/customer/8e78aa909ec941c2b5cccff7be967311",
        "rel": "detail"
      },
      "uuid": "8e78aa909ec941c2b5cccff7be967311",
      "name": "00000000000001",
      "customerId": 163
    },
    {
      "link": {
        "url": "https://api.fieldaware.net/customer/fb510a062e5342d5a63bdc27739aa267",
        "rel": "detail"
      },
      "uuid": "fb510a062e5342d5a63bdc27739aa267",
      "name": "01010101010101010101010101",
      "customerId": 212
    }
  ],
  "page": 0,
  "sortedBy": []
}

Query Parameters:

sortedBy – Can be ordered by name and customerId
taxable – Boolean denoting filtering by taxable customer
name – A filtering value for customer name
glAccount – A filtering value for glAccount

Response JSON Object:

number (int) – Total number of customers
items (array) – A list of JSON objects representing customers
page (int) – Page number
sortedBy (array) – A list of ordered by (strings), can be name and customerId
pageSize (int) – NUmber of JSON objects (representing customers) by page.

Retrieve resources - filtering¶

GET /location/¶

Retrieving locations using filter locality

Sample request:

GET /location/?locality=Dublin HTTP/1.1
Host: api.fieldaware.net
Authorization: Token d943a51d68c44ca38cab9abda20a4d18
Accept: application/json

Query Parameters:

locality – response body will contain only resources (in this case locations) that match the filter locality

Sample response:

Note: in the example below the list of items is shortened for illustration purpose.

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.fieldaware.net/location/?page=0&locality=Dublin>; rel=first,
      <https://api.fieldaware.net/location/?page=0&locality=Dublin>; rel=last

{
  "count": 19,
  "pageSize": 20,
  "items": [
    {
      "customer": {
        "link": {
          "url": "https://api.fieldaware.net/customer/1f81818230e8441f8da97cc1dd944052",
          "rel": "detail"
        },
        "uuid": "1f81818230e8441f8da97cc1dd944052"
      },
      "locality": "Dublin",
      "link": {
        "url": "https://api.fieldaware.net/location/02fd1f8352f1498f8fb900d131f7eb07",
        "rel": "detail"
      },
      "uuid": "02fd1f8352f1498f8fb900d131f7eb07",
      "name": "88 Lower Leeson Street"
    },
  ],
  "page": 0,
  "sortedBy": []
}

Response JSON Object:

count (int) – Total number of items (in this case locations already filtered)
pageSize (int) – Number of JSON objects (representing locations) by page.
items (array) – A list of JSON objects representing locations.
page (int) – Page number (default value is 0)
sortedBy (array) – A list of ordered by (strings)

Retrieve resources - page size¶

GET /location/¶

Using a parameter pageSize user can increase number of items (in this case locations) returned in JSON response body. Please note that max page size is 100 items.

Sample request:

GET /location/?pageSize=100 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token d943a51d68c44ca38cab9abda20a4d18
Accept: application/json

Query Parameters:

pageSize – Response body will contain a list of max number of items = 100 (unless total number of items is < 100)

Sample response:

Note: in the example below the list of items is shortened for illustration purpose.

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.fieldaware.net/location/?page=0&pageSize=100>; rel=first,
      <https://api.fieldaware.net/location/?page=2&pageSize=100>; rel=last,
      <https://api.fieldaware.net/location/?page=1&pageSize=100>; rel=next

{
  "count": 269,
  "pageSize": 100,
  "items": [
    {
      "customer": {
        "link": {
          "url": "https://api.fieldaware.net/customer/fc3bccb614204e2987fdcc4a0967ac59",
          "rel": "detail"
        },
        "uuid": "fc3bccb614204e2987fdcc4a0967ac59"
      },
      "locality": "Dublin 2",
      "link": {
        "url": "https://api.fieldaware.net/location/01f5c5260b664249b8821ed5d0ddfeeb",
        "rel": "detail"
      },
      "uuid": "01f5c5260b664249b8821ed5d0ddfeeb",
      "name": "LocationXYU"
    },
  ],
  "sortedBy": [],
  "page": 0
}

Response JSON Object:

count (int) – Total number of items (in this case locations)
pageSize (int) – Number of JSON objects (representing locations) by page
items (array) – A list of JSON objects representing locations
sortedBy (array) – A list of ordered by (strings)
page (int) – Page number (default value is 0)

Retrieve resources - pagination¶

GET /location/¶

Using a parameter page user can request certain part of a list of resources. Please note that default page number is 0. By increasing the page number in subsequent requests user can ‘iterate’ through full list of items until the list is empty.

Sample request:

GET /location/?page=1 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token d943a51d68c44ca38cab9abda20a4d18
Accept: application/json

Query Parameters:

page – Requested page number (default pageSize is 20)

Sample response:

Note: in the example below the list of items is shortened for illustration purpose.

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.fieldaware.net/location/?page=0>; rel=first,
      <https://api.fieldaware.net/location/?page=13>; rel=last,
      <https://api.fieldaware.net/location/?page=0>; rel=prev,
      <https://api.fieldaware.net/location/?page=2>; rel=next

{
  "count": 269,
  "pageSize": 20,
  "items": [
    {
      "customer": {
        "link": {
          "url": "https://api.fieldaware.net/customer/cd9b4a385409407a941405a485f42dd3",
          "rel": "detail"
        },
        "uuid": "cd9b4a385409407a941405a485f42dd3"
      },
      "locality": "D",
      "link": {
        "url": "https://api.fieldaware.net/location/12bb254c564b48a3bf89d2f345c2bcc9",
        "rel": "detail"
      },
      "uuid": "12bb254c564b48a3bf89d2f345c2bcc9",
      "name": null
    },
  ],
  "sortedBy": [],
  "page": 1
}

Response JSON Object:

count (int) – Total number of items (in this case locations)
pageSize (int) – Number of JSON objects (representing locations) by page
items (array) – A list of JSON objects representing locations
sortedBy (array) – A list of ordered by (strings)
page (int) – Page number (requested value was 1)

Retrieve resources - pagination and page size¶

GET /location/¶

Combining parameters page and pageSize

Sample request:

GET /location/?pageSize=100&page=2 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token d943a51d68c44ca38cab9abda20a4d18
Accept: application/json

Query Parameters:

pageSize – Number of items returned in JSON response body
page – Requested page number (default pageSize is 20)

Sample response:

Note: in the example below the list of items is shortened for illustration purpose.

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.fieldaware.net/location/?page=0&pageSize=100>; rel=first,
      <https://api.fieldaware.net/location/?page=2&pageSize=100>; rel=last,
      <https://api.fieldaware.net/location/?page=1&pageSize=100>; rel=prev

{
  "count": 269,
  "pageSize": 100,
  "items": [
    {
      "customer": {
        "link": {
          "url": "https://api.fieldaware.net/customer/2acb109f143c4f53b877c983ebce19b2",
            "rel": "detail"
          },
          "uuid": "2acb109f143c4f53b877c983ebce19b2"
        },
      "locality": "Plano",
      "link": {
        "url": "https://api.fieldaware.net/location/b769f9878e8a432580c72c26cdcc0ea4",
        "rel": "detail"
      },
      "uuid": "b769f9878e8a432580c72c26cdcc0ea4",
      "name": null
    },
  ],
  "sortedBy": [],
  "page": 2
}

Response JSON Object:

count (int) – Total number of items (in this case locations)
pageSize (int) – Number of JSON objects (representing locations)
items (array) – A list of JSON objects representing locations
sortedBy (array) – A list of ordered by (strings)
page (int) – Page number (requested value was 2)

Retrieve resources - pagination, page size and filters¶

GET /location/¶

Combining parameters page and pageSize and filters.

Sample request:

GET /location/?pageSize=5&page=2&locality=Dublin HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 687fe20baeef448bb30db579139dad33
Accept: application/json

Query Parameters:

pageSize – Number of items returned in JSON response body
page – Requested page number (default pageSize is 20)
locality – Filter results (in this case by locality)

Sample response:

Note: in the example below the list of items is shortened for illustration purpose.

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.fieldaware.net/location/?page=0&pageSize=5&locality=Dublin>; rel=first,
      <https://api.fieldaware.net/location/?page=3&pageSize=5&locality=Dublin>; rel=last,
      <https://api.fieldaware.net/location/?page=1&pageSize=5&locality=Dublin>; rel=prev,
      <https://api.fieldaware.net/location/?page=3&pageSize=5&locality=Dublin>; rel=next

{
  "count": 19,
  "pageSize": 5,
  "items": [
    {
      "customer": {
        "link": {
          "url": "https://api.fieldaware.net/customer/6da8d036f0d24d50b4519c12ad5398eb",
          "rel": "detail"
        },
        "uuid": "6da8d036f0d24d50b4519c12ad5398eb"
      },
      "locality": "Dublin",
      "link": {
        "url": "https://api.fieldaware.net/location/9449a0355dd549aa9e0ea4cc5e53238f",
        "rel": "detail"
      },
      "uuid": "9449a0355dd549aa9e0ea4cc5e53238f",
      "name": "Location test"
    },
  ],
  "sortedBy": [],
  "page": 2
}

Response JSON Object:

count (int) – Total number of items (in this case locations)
pageSize (int) – Number of JSON objects (representing locations)
items (array) – A list of JSON objects representing locations
sortedBy (array) – A list of ordered by (strings)
page (int) – Page number (requested value was 2)

Retrieving and sorting resources¶

GET /customer/¶

Sample request:

GET /customer/?sortedBy=customerId&pageSize=5&page=1 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 687fe20baeef448bb30db579139dad33
Accept: application/json

Query Parameters:

sortedBy – A parameter used to sort returned items (in JSON response body)
pageSize – A parameter used to limit number of items in returned JSON body
page – A parameter used to specify what page of results to return

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.fieldaware.net/customer/?sortedBy=customerId&page=0&pageSize=5>; rel=first,
      <https://api.fieldaware.net/customer/?sortedBy=customerId&page=38&pageSize=5>; rel=last,
      <https://api.fieldaware.net/customer/?sortedBy=customerId&page=0&pageSize=5>; rel=prev,
      <https://api.fieldaware.net/customer/?sortedBy=customerId&page=2&pageSize=5>; rel=next

{
  "count": 190,
  "pageSize": 5,
  "items": [
    {
      "link": {
        "url": "https://api.fieldaware.net/customer/1368ade111284d90953ec8674587d4dc",
        "rel": "detail"
      },
      "uuid": "1368ade111284d90953ec8674587d4dc",
      "name": "University of Dublin",
      "customerId": 6
    },
    {
      "link": {
        "url": "https://api.fieldaware.net/customer/16b10e1ad4a041fe82dd60fdbadefc35",
        "rel": "detail"
      },
      "uuid": "16b10e1ad4a041fe82dd60fdbadefc35",
      "name": "Emma Awards",
      "customerId": 7
    },
    {
      "link": {
        "url": "https://api.fieldaware.net/customer/1d49eee5f5de4196ba889cb004b8b5f8",
        "rel": "detail"
      },
      "uuid": "1d49eee5f5de4196ba889cb004b8b5f8",
      "name": "Boss Mechanical",
      "customerId": 8
    },
    {
      "link": {
        "url": "https://api.fieldaware.net/customer/20325dcf52e44661a63a23bd7333a82e",
        "rel": "detail"
      },
      "uuid": "20325dcf52e44661a63a23bd7333a82e",
      "name": "Shop Properties",
      "customerId": 9
    },
    {
      "link": {
        "url": "https://api.fieldaware.net/customer/258ff059a24d47ab8ec8860c9a3eed02",
        "rel": "detail"
      },
      "uuid": "258ff059a24d47ab8ec8860c9a3eed02",
      "name": "Ray Brown",
      "customerId": 10
    }
  ],
  "sortedBy": ["customerId"],
  "page": 1
}

Response JSON Object:

count (int) – Indicates total number of items (in this case customers)
pageSize (int) – Indicates how many items is returned in each page (in this case 5)
items (array) – A list of JSON objects representing customers (in this case sorted by customerId)
sortedBy (array) – A list of parameters (strings) used to sort response results (in this case customerId)
page (int) – Page number