Unavailable Time
----------------------

.. warning::
  The following endpoints are accessible only if the Unavailable Time feature
  is enabled for the organisation using the API.
  Expect a 403 error (Forbidden) otherwise.

This API allows listing and retrieving Unavailable Time Types and Unavailable Times for a specific user.
Unavailable Time Types and Unavailable Times are identified by their UUID.
Unavailable Time Types can be created/updated/deleted only by WebApp users, as they are read-only on the API.


List Unavailable Time Types
...........................

.. http:get:: /unavailability/types

   List all Unavailable Time Types.

   **Sample request**:

   .. sourcecode:: http

      GET /unavailability/types?pageSize=2 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

   :query sortedBy: Available sorting criteria: ``name``
   :query archived: Optional boolean denoting if an archived Unavailable Time Type must be retrieved
   :query name: Optional string to return only Unavailable Time Types whose name contains this value

   **Sample response**:

   .. sourcecode:: http

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


      {
          "count": 5,
          "items": [
              {
                  "uuid": "e4883fb60a9f478a857baca030da935d",
                  "name": "PTO",
                  "description": "Use to book personal time off",
                  "archived": false,
                  "paid": false,
                  "link": {
                    "rel": "detail",
                    "url": "https://api.fieldaware.net/unavailability/types/e4883fb60a9f478a857baca030da935d"
                  }
              },
              {
                  "uuid": "8b2e54a163bd40618e2d80cf7870c09b",
                  "name": "Training",
                  "description": "Use for company training",
                  "archived": false,
                  "paid": false,
                  "link": {
                    "rel": "detail",
                    "url": "https://api.fieldaware.net/unavailability/types/8b2e54a163bd40618e2d80cf7870c09b"
                  }
              }
          ],
          "page": 0,
          "pageSize": 2,
          "sortedBy": [
              "name"
          ]
      }

   :statuscode 200: resources retrieved successfully
   :statuscode 422: validation error


Get Unavailable Time Type
.........................

.. http:get:: /unavailability/types/(type_ref)

   Retrieve a given Unavailable Time Type.


   **Sample request**:

   .. sourcecode:: http

      GET /unavailability/types/8b2e54a163bd40618e2d80cf7870c09b HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

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


      {
          "uuid": "8b2e54a163bd40618e2d80cf7870c09b",
          "name": "PTO",
          "description": "Use to book personal time off",
          "archived": false,
          "paid": false
      }

   :statuscode 200: resource retrieved successfully
   :statuscode 404: resource not found


List Unavailable Times
......................

.. http:get:: /user/(user_ref)/unavailability

   List all Unavailable Times for a specific user, optionally restricted to a given time window.

   The *<start date>* and *<end date>* parameters must be given in ISO 8601 format,
   and need to be URL-encoded where appropriate.

   **Sample request**:

   .. sourcecode:: http

      GET /user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability?pageSize=2 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

   :query sortedBy: Available sorting criteria: ``start``, ``uuid``
   :query start: Optional filtering value for ``start`` date
   :query end: Optional filtering value for ``end`` date

   **Sample response**:

   .. sourcecode:: http

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


      {
          "count": 5,
          "items": [
              {
                  "uuid": "6f4214df45a34ab3a1664920e8505292",
                  "start": "2019-03-20T00:00:00+00:00",
                  "end": "2019-03-20T23:59:59+00:00",
                  "details": "Personal time off",
                  "type": {
                      "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
                  },
                  "link": {
                    "rel": "detail",
                    "url": "https://api.fieldaware.net/user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/6f4214df45a34ab3a1664920e8505292"
                  }
              },
              {
                  "uuid": "dc42f6fadc794665b2953f932e4c102e",
                  "start": "2019-03-23T00:00:00+00:00",
                  "end": "2019-03-23T23:59:59+00:00",
                  "details": "Personal time off",
                  "type": {
                      "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
                  },
                  "link": {
                    "rel": "detail",
                    "url": "https://api.fieldaware.net/user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/dc42f6fadc794665b2953f932e4c102e"
                  }
              }
          ],
          "page": 0,
          "pageSize": 2,
          "sortedBy": [
              "start",
              "uuid"
          ]
      }

   :statuscode 200: resources retrieved successfully
   :statuscode 422: validation error


Get Unavailable Time
....................

.. http:get:: /user/(user_ref)/unavailability/(unavailable_time_ref)

   Retrieve a given Unavailable Time for a specific user.


   **Sample request**:

   .. sourcecode:: http

      GET /user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/6f4214df45a34ab3a1664920e8505292 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

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


      {
          "uuid": "6f4214df45a34ab3a1664920e8505292",
          "start": "2019-03-20T00:00:00+00:00",
          "end": "2019-03-20T23:59:59+00:00",
          "details": "Personal time off",
          "type": {
              "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
          }
      }

   :statuscode 200: resource retrieved successfully
   :statuscode 404: resource not found


Create Unavailable Time
.......................

.. http:post:: /user/(user_ref)/unavailability

   Create a new Unavailable Time for a specific user.

   The following restrictions apply:

   - You can't have overlapping Unavailable Times for the same user.
   - You can't create an Unavailable Time specifying a type that's been archived.
   - If your organisation is Enterprise-enabled, you can't create an Unavailable Time for users
     in other branches you don't have full access to.


   **Sample request**:

   .. sourcecode:: http

      POST /user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

      {
         "start": "2019-04-14T10:00:00+01:00",
         "end": "2019-04-14T12:00:00+01:00",
         "details": "Personal time off",
         "type": {
            "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
         }
      }

   :<json string start: ISO-formatted starting datetime (required)
   :<json string end: ISO-formatted end datetime (required)
   :<json string details: Description of the new Unavailable Time (optional)
   :<json string type.uuid: Unique identifier (UUID) of the Unavailable Time Type (required)


   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED

      {
         "start": "2019-04-14T09:00:00+00:00",
         "link": {
            "url": "https://api.fieldaware.net/user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/379cdd559bee4eaea01edbde9ebc15e7",
            "rel": "detail"
         },
         "uuid": "379cdd559bee4eaea01edbde9ebc15e7",
         "end": "2019-04-14T11:00:00+00:00",
         "type": {
            "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
         },
         "details": "Personal time off"
      }

   :statuscode 201: created successfully
   :statuscode 422: validation error


Update Unavailable Time
.......................

.. http:put:: /user/(user_ref)/unavailability/(unavailable_time_ref)

   Update an existing Unavailable Time for a specific user.

   All fields are optional, and only the specified fields will be updated.

   The following restrictions apply:

   - You can't have overlapping Unavailable Times for the same user.
   - You can't update an Unavailable Time to a type that's been archived,
     but you can update an instance of Unavailable Time that already has an archived type.
   - If your organisation is Enterprise-enabled, you can't update an Unavailable Time for users
     in other branches you don't have full access to.


   **Sample request**:

   .. sourcecode:: http

      PUT /user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/379cdd559bee4eaea01edbde9ebc15e7 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json

      {
         "start": "2019-04-15T10:00:00+01:00",
         "end": "2019-04-15T12:00:00+01:00",
         "details": "Other personal time off",
         "type": {
            "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
         }
      }

   :<json string start: ISO-formatted starting datetime (optional)
   :<json string end: ISO-formatted end datetime (optional)
   :<json string details: Description of the new Unavailable Time (optional)
   :<json string type.uuid: Unique identifier (UUID) of the Unavailable Time Type (optional)


   :statuscode 204: resource updated successfully
   :statuscode 422: validation error
   :statuscode 404: resource not found



Delete Unavailable Time
.......................

.. http:delete:: /user/(user_ref)/unavailability/(unavailable_time_ref)

   Delete an existing Unavailable Time for a specific user.

   The following restriction applies:

   - You can't delete an Unavailable Time for users in other branches you don't have full access to.


   **Sample request**:

   .. sourcecode:: http

      DELETE /user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/379cdd559bee4eaea01edbde9ebc15e7 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Content-Type: application/json
      Accept: application/json


   :statuscode 204: resource deleted successfully
   :statuscode 404: resource not found