Service areas
-------------

This API allows listing, retrieving, creating, updating,
and deleting service areas. Service areas are identified by their UUID.


List Tasks
..........

.. http:get:: /service_area/

   List all service areas.

   **Sample request**:

   .. sourcecode:: http

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

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "count": 100,
        "items": [
          {
            "name": "South Inner",
            "uuid": "01c9373d6d22438096503fe72a7c1612",
            "link": {
              "rel": "detail",
              "url": "https://api.fieldaware.net/service_area/01c9373d6d22438096503fe72a7c1612"
            }
          },
          {
            "name": "North Florida",
            "uuid": "01f359aabafb4ff28347bddd9a24f28a",
            "link": {
              "rel": "detail",
              "url": "https://api.fieldaware.net/service_area/01f359aabafb4ff28347bddd9a24f28a"
            }
          },
          {
            "name": "Key West",
            "uuid": "0274f3fa2e224e17ba9e6a36ce3f4b0a",
            "link": {
              "rel": "detail",
              "url": "https://api.fieldaware.net/service_area/0274f3fa2e224e17ba9e6a36ce3f4b0a"
            }
          }
        ],
        "page": 0,
        "pageSize": 3,
        "sortedBy": []
      }

   :query sortedBy: Available sorting criteria: ``name``
   :query name: A filtering value for service area name


Get Service Area
................

.. http:get:: /service_area/(area_ref)

   Retrieve a given service area.

   **Sample request**:

   .. sourcecode:: http

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

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "name": "Yuge rectangle",
        "description": "Nice rectangular shape",
        "colour": "123132",
        "area": {
          "shape": "RECTANGLE",
          "geometry": {
            "ne": {"lat": 0, "lng": 0},
            "sw": {"lat": 1, "lng": 1}
          }
        }
      }


Create Service Area
...................

.. http:post:: /service_area/

   Create a new service area.

   **Sample request**:

   .. sourcecode:: http

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

      {
        "name": "Yuge rectangle",
        "description": "Nice rectangular shape",
        "colour": "123132",
        "area": {
          "shape": "RECTANGLE",
          "geometry": {
            "ne": {"lat": 0, "lng": 0},
            "sw": {"lat": 1, "lng": 1}
          }
        }
      }

   :<json string name: Name of the service area (required)
   :<json string description: Description of the service area
   :<json string colour: colour to visualize the area on a map, expressed with a HTML hex colour code. E.g. "FFFFFF" for white
   :<json obj area: mapping to define the shape of the service area


   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Content-Type: application/json


Update Service Area
...................

.. http:put:: /service_area/(area_ref)

   Update a given service area.

   **Sample request**:

   Same as `Create Service Area`_, with all properties being optional.

   .. sourcecode:: http

     PUT /service_area/00bd62a92a004faea233951510167cad HTTP/1.1
     Host: api.fieldaware.net
     Authorization: Token 687fe20baeef448bb30db579139dad33
     Accept: application/json

     {
       "name": "Brooklyn"
     }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT


Delete Service Area
...................

.. http:delete:: /service_area/(area_ref)

   Delete a given service area.

   **Sample request**:

   .. sourcecode:: http

      DELETE /service_area/00bd62a92a004faea233951510167cad HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

    HTTP/1.1 204 No Content


Defining Areas
..............

Service areas define polygonal areas on a map. There are two kinds of valid service
area shapes: rectangles and linear rings. These shapes are specified by providing a number
of geographical coordinates (latitude, longitude) corresponding to the opposing corners
of a rectangle, or the vertices of a polygon.

**Rectangle**

A rectangular shape is defined by two coordinates (latitude, longitude)
that correspond with the North East and South West corners of the rectangle.

**Sample payload for a rectangular service area**

.. sourcecode:: http

  {
    "name": "Rectangular area",
    "description": "Nice rectangular shape",
    "colour": "FFFFFF",
    "area": {
      "shape": "RECTANGLE",
      "geometry": {
        "ne": {"lat": 0, "lng": 0},
        "sw": {"lat": 1, "lng": 1}
      }
    }
  }

**Linear ring**

A linear ring defines a polygonal area from a collection of coordinates.
The minimum number of vertices provided to define an area is three.

**Sample payload for a linear ring area**

.. sourcecode:: http

  {
    "name": "Triangular area",
    "description": "Nice rectangular shape",
    "colour": "CDCDCD",
    "area": {
      "shape": "LINEAR_RING",
      "geometry": [
        {"lat": 0, "lng": 0},
        {"lat": 1, "lng": 1},
        {"lat": 3, "lng": 2}
      ]
    }
  }