.. _assets:

Assets
------

This API allows listing, retrieving, creating, updating and deleting assets.
Assets are identified by their UUID.


List Assets
...........

.. http:get:: /asset/

   List all assets.

   **Sample request**:

   .. sourcecode:: http

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

   :query name: A filtering value for name
   :query serialNumber: A filtering value for serialNumber
   :query manufacturer: A filtering value for manufacturer
   :query make: A filtering value for make
   :query model: A filtering value for model
   :query sortedBy:  Available sorting criteria: ``name``

   **Sample response**:

   .. sourcecode:: http

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

      {
        "count": 18,
        "items": [
          {
            "href": {
              "rel": "detail",
              "url": "https://api.fieldaware.net/asset/acac7c59d87b41e8ad92223cd870e2d3"
            },
            "name": "1068",
            "uuid": "acac7c59d87b41e8ad92223cd870e2d3"
          },
          {
            "href": {
              "rel": "detail",
              "url": "https://api.fieldaware.net/asset/6f0c84429423417ab7bbc16a253471c0"
            },
            "name": "1070",
            "uuid": "6f0c84429423417ab7bbc16a253471c0"
          },
        ],
        "pageSize": 20,
        "pageStartIndex": 0,
        "sortedBy": []
      }

   :>json int count: Number of assets.
   :>json array items: An array of JSON objects (items).
   :>json int pageSize: How many items is in the page.
   :>json int pageStartIndex: Page number.
   :>json array sortedBy: A list of sorting criteria.


Get Asset
.........

.. http:get:: /asset/(asset_ref)

   Retrieve a given asset.

   **Sample request**:

   .. sourcecode:: http

      GET /asset/acac7c59d87b41e8ad92223cd870e2d3 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

      {
        "area": "Bonnyville",
        "contact": null,
        "customFields": {
          "3a6eff2c2f1a4009adeb504aa1389fe7": "Bonnyville"
        },
        "description": null,
        "location": {
          "country": "",
          "href": {
            "rel": "detail",
            "url": "https://api.fieldaware.net/location/48c663316b154db598db225bcf404016"
          },
          "isBilling": false,
          "lat": null,
          "lng": null,
          "locality": "Houston",
          "name": "North Houston",
          "postcode": "77079",
          "region": "TX"
          "streetName": "11211 KATY FREEWAY, STE 450",
          "type": null,
          "uuid": "48c663316b154db598db225bcf404016"
        },
        "maintenanceNotes": null,
        "make": "A1 Oil & Gas Company",
        "manufacturer": null,
        "manufacturerNotes": null,
        "model": "122H",
        "name": "1068",
        "serialNumber": "847603409458763",
        "uuid': "acac7c59d87b41e8ad92223cd870e2d3"
      }

   :>json string area: Area of the asset
   :>json obj contact: JSON Obj, details of a contact assigned to the asset or null
   :>json obj customFields: JSON Obj, custom fields of the asset
   :>json string description: Asset description or null
   :>json obj location: Asset location JSON Obj
   :>json string maintenanceNotes: Maintenance notes or null
   :>json string make: Asset maker
   :>json string manufacturerNotes: Notes about the asset
   :>json string model: Asset model
   :>json string name: Name of the asset
   :>json string serialNumber: Serial number of the asset
   :>json string uuid: UUID number of the asset


Create Asset
............

.. http:post:: /asset/

   Create a new asset.

   **Sample request**:

   .. sourcecode:: http

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

      {
        "name": "Asset001",
        "location": {
          "uuid": "01f5c5260b664249b8821ed5d0ddfeeb"
        },
        "description": "Description of the asset",
        "serialNumber": "WS23",
        "make": "Maker001",
        "model": "Model-YT23",
        "manufacturer": "Bosh",
        "manufacturerNotes": "Havy duty drill",
        "maintenanceNotes": "Maintenance notes of the asset",
        "area": "2nd shelf, storage id U345",
        "arrivedOn": "2014-01-01",
        "contact": {
          "uuid": "01f5c5260b664249b8821ed5d0ddfxxv"
        },
        "customFields": {
          "09v5c5260b664249b8821ed5d0ddfcxv": "Checked?"}
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/asset/6ae23a90f3b149b69c45eec1a125ea67"

      {
        "link": {
          "url": "https://api.fieldaware.net/asset/6ae23a90f3b149b69c45eec1a125ea67",
          "rel": "detail"
        },
        "maintenanceNotes": "Havy duty drill",
        "description":  "Description of the asset",
        "area": "2nd shelf, storage id U345",
        "make": "Maker001",
        "serialNumber": "WS23",
        "contact": null,
        "attachments": [],
        "manufacturerNotes": "",
        "location": {
          "uuid": "01f5c5260b664249b8821ed5d0ddfxxv"
        },
        "model": "Model-YT23",
        "manufacturer": "Bosh",
        "customFields": {
          "09v5c5260b664249b8821ed5d0ddfcxv": "Checked?"
        },
        "name": "Asset001"
      }

   :<json string name: Name of the asset (required).
   :<json obj location: Location of the asset (required).
   :<json string description: Description of the asset.
   :<json string serialNumber: Serial number of the asset.
   :<json string make: Make of the asset.
   :<json string model: Model of the asset.
   :<json string manufacturer: Manufacturer of the asset.
   :<json string manufacturerNotes: Manufacturer notes about the asset.
   :<json string maintenanceNotes: Maintenance notes of the asset.
   :<json string area: Specific area within the location where the asset is located.
   :<json datetime arrvedOn: When the asset arrived at this location.
   :<json obj contact: Contact person for this asset movement.
   :<json obj customFields: Mapping of declaration keys to values.


.. http:post:: /asset/

   Create a new minimal asset.

   **Sample request**:

   .. sourcecode:: http

      POST /asset/ HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

      {
        "name": "Hammer",
        "location": {
          "uuid": "01f5c5260b664249b8821ed5d0ddfeeb"
        }
      }

   :<json string name: Name of the asset (required).
   :<json obj location: Location of the asset (required).

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED
      Content-Type: application/json
      Location: "https://api.fieldaware.net/asset/6ae23a90f3b149b69c45eec1a125ea67"

      {
        "link": {
          "url": "https://api.fieldaware.net/asset/6ae23a90f3b149b69c45eec1a125ea67",
          "rel": "detail"
        },
        "uuid": "6ae23a90f3b149b69c45eec1a125ea67"
      }

   :>json obj link: JSON object
   :>json string uuid: UUID number of the created asset


Update Asset
............

.. http:put:: /asset/(asset_ref)

   Update a given asset.

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

   .. warning:: Update of asset's location also updates locations of all
    unfinished and not yet started jobs associated with the given asset.
    Moreover, job's location and contact have to agree on a customer they refer
    to.  So in order to prevent an inconsistency, **contacts of all jobs
    associated with the said asset are set to** ``null`` by such a request.

   **Sample request**:

   .. sourcecode:: http

      PUT /asset/cac8a7efc2224e859457d6704f4fd0ba HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 687fe20baeef448bb30db579139dad33
      Accept: application/json

      {
        "name": "Asset001",
        "location": {
          "uuid": "01f5c5260b664249b8821ed5d0ddfeeb"
        },
        "serialNumber": "S/N 1000-23",
        "manufacturer": "Makita"
      }

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 NO CONTENT


Delete Asset
............

.. http:delete:: /asset/(asset_ref)

   Delete a given asset.

   **Sample request**:

   .. sourcecode:: http

      DELETE /asset/e764e03bef8d4a29be0a8dceb4d1e6fe HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204 No Content


Add Asset Attachments
.....................

.. http:post:: /asset/(asset_ref)/attachment/

   Add an a attachment to a given asset.

   **Sample request**:

   .. sourcecode:: http

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

   **Sample response**:

   .. sourcecode:: http

      HTTP/1.1 204

      [
        {
          "mimetype": "image/png",
          "createdDate": "2013-08-11T14:00:00+00:00",
          "uuid": "a3aa9575739c43989bfec0fca014d3d0",
          "name": "filename.png"
        }
      ]


List of Asset Attachments
.........................

.. http:get:: /asset/(asset_ref)/attachment/

   **Sample request**:

   .. sourcecode:: http

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

   **Sample response**:

   .. sourcecode:: http

    [
      {
        "mimetype": "image/png",
        "createdDate": "2013-08-11T14:00:00+00:00",
        "uuid": "a3aa9575739c43989bfec0fca014d3d0",
        "caption": "file description",
        "name": "file.png"
      }
    ]


Download Asset Attachment
.........................

.. http:get:: /asset/(asset_ref)/attachment/(attachment_ref)

   Download a given file attached to a given asset.

   The asset is specified by its UUID. The attachment is also
   specified by its UUID, as returned by `Add Asset Attachments`_.

   :statuscode 404: resource not found


Update Asset Attachment caption
...............................

.. http:put:: /asset/(asset_ref)/attachment/(attachment_ref)

    You can update the attachment caption

   **Sample request**:

   .. sourcecode:: http

      PUT /asset/e764e03bef8d4a29be0a8dceb4d1e6fe/attachment/a3aa9575739c43989bfec0fca014d3d0 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Accept: application/json

      {
        "caption": "caption text"
      }

   **Sample response**:

   .. sourcecode:: http

    HTTP/1.1 204 No Content


Delete Asset Attachment
.......................

.. http:delete:: /asset/(asset_ref)/attachment/(attachment_ref)

    Removes an attachment from an asset

   **Sample request**:

   .. sourcecode:: http

      DELETE /asset/e764e03bef8d4a29be0a8dceb4d1e6fe/attachment/a3aa9575739c43989bfec0fca014d3d0 HTTP/1.1
      Host: api.fieldaware.net
      Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
      Accept: application/json

   **Sample response**:

   .. sourcecode:: http

    HTTP/1.1 204 No Content