Retrieving resource collections
-------------------------------

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

Pagination
..........

:pageSize: :ref:`integer-type`, the number of items in each page.
:page: :ref:`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:

.. code-block:: javascript

    <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: :ref:`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).

    .. code-block:: http

      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:

    .. code-block:: http

      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
..................................

.. http:get:: /customer/

   GET request without filters returning a list of customers

   **Sample request**:

   .. sourcecode:: http

      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.

   .. sourcecode:: http

      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 sortedBy: Can be ordered by ``name`` and ``customerId``
   :query taxable: Boolean denoting filtering by taxable customer
   :query name: A filtering value for customer name
   :query glAccount: A filtering value for glAccount
   :>json int number: Total number of customers
   :>json array items: A list of JSON objects representing customers
   :>json int page: Page number
   :>json array sortedBy: A list of ordered by (strings), can be ``name`` and ``customerId``
   :>json int pageSize: NUmber of JSON objects (representing customers) by page.


Retrieve resources - filtering
..............................

.. http:get:: /location/

   Retrieving locations using filter ``locality``

   **Sample request**:

   .. sourcecode:: http

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

   :query 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.

   .. sourcecode:: http

      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": []
      }

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


Retrieve resources - page size
..............................

.. http: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**:

   .. sourcecode:: http

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

   :query 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.

   .. sourcecode:: http

      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
      }

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


Retrieve resources - pagination
...............................

.. http: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**:

   .. sourcecode:: http

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

   :query page: Requested page number (default ``pageSize`` is 20)

   **Sample response**:

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

   .. sourcecode:: http

      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
      }

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


Retrieve resources - pagination and page size
.............................................

.. http:get:: /location/

   Combining parameters ``page`` and ``pageSize``

   **Sample request**:

   .. sourcecode:: http

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

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

   **Sample response**:

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

   .. sourcecode:: http

      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
      }

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


Retrieve resources - pagination, page size and filters
......................................................

.. http:get:: /location/

   Combining parameters ``page`` and ``pageSize`` and filters.

   **Sample request**:

   .. sourcecode:: http

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

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

   **Sample response**:

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

   .. sourcecode:: http

      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
      }

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


Retrieving and sorting resources
................................

.. http:get:: /customer/

   **Sample request**:

   .. sourcecode:: http

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

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

   **Sample response**:

   .. sourcecode:: http

      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
      }

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