Getting Started
===============

This section explains how to get started with the FieldAware API. It assumes familiarity with the FieldAware product concepts and basic HTTP concepts.


Making Your First Request
-------------------------

To make requests on the API, an HTTP client or client library is needed. We illustrate
the process using `cURL <http://curl.haxx.se/>`__, a widely available command-line tool. We
also use the `jq <http://stedolan.github.io/jq/>`__ tool to format any JSON output.
There are other equally convenient tools available. For example,
there are browser plugins such as 
`RESTClient <https://addons.mozilla.org/en-US/firefox/addon/restclient/>`__ (Firefox), or
`Postman <https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en>`__ (Chrome), 
or standalone clients such as `Fiddler <http://www.telerik.com/download/fiddler>`__, or 
`rest-client <https://code.google.com/p/rest-client/>`__. The process is in all cases the same.


To make a request to the *base URL* of the API using cURL: 

.. sourcecode:: bash

    curl -i https://api.fieldaware.net

.. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json
    Content-Length: 61
    Connection: keep-alive

    {"api": "1.0", "version": "1.19.20", "service": "fieldaware"}

The base URL is the root of the API domain, all API resources are on this domain.

Note that it is necessary to use the HTTPS protocol. This to ensure that data does not travel over the Internet unencrypted. Requests over plain HTTP are not supported, and are met with an ``HTTP 400 Bad Request`` error.

For most resources, authentication is needed. Authentication is achieved by including an API key as part of a request. The API key may be passed in as a query parameter for GET requests. API keys are associated with users. The API exposes an ``whoami`` endpoint to identify the user associated with a key:

.. sourcecode:: bash
 
  curl -s https://api.fieldaware.net/auth/whoami?api_key=9dcae3660ec84eac94bb506e09a9af40 | jq .

  {
    "user_url": "https://api.fieldaware.net/user/57e226d06c6b455d9c1acff8e4cb714d",
    "uuid": "57e226d06c6b455d9c1acff8e4cb714d",
    "roles": ["admin"],
    "email": "servicemanager@murphy.com"
  }


The recommended way of passing the API key, is in the ``Authorization`` header of the request. This works for all HTTP verbs, but for POST, PUT, and DELETE requests, which don't support query parameters, it is the only way. The header has the following format: ``Authorization: Token API_KEY``, where ``API_KEY`` is the your API key. Note the space, and the absence of any further delimiters.

Retrieving the User resource linked to in the above result, using **header-based** authentication, can happen as follows:

.. sourcecode:: bash

  curl -s \
       -H "Authorization: Token 9dcae3660ec84eac94bb506e09a9af40" \
       -H "Accept-Type: application/json" \
       https://api.fieldaware.net/user/57e226d06c6b455d9c1acff8e4cb714d | jq .

  {
      "archived": false,
      "uuid": "57e226d06c6b455d9c1acff8e4cb714d",
      "firstName": "Service",
      "platform": "online",
      "locale": "en_US",
      "lastName": "Manager",
      "phone": null,
      "role": "Manager",
      "timezone": "US/Central",
      "customFields": {},
      "email": "servicemanager@murphy.com"
  }


Note that the cURL command also specifies an ``Accept`` header to indicate that the preferred resource representation is ``application/json``. At the moment, the API returns JSON by default, but it is best practice to explicitly include an ``Accept`` header in any request. Similarly, to update the a resource, a ``Content-Type`` header must be used to indicate to the server how the payload is encoded. At the moment, the API only supports JSON payloads. This may change in the future.

Updating the above User resource can happen with a PUT request. The API admits a partial resource representation in the payload of PUT requests. The following request sets the ``phone`` attribute of the user, but keeps the other attributes to their existing values. 

.. sourcecode:: bash

  curl -X PUT \
       -H "Authorization: Token 9dcae3660ec84eac94bb506e09a9af40" \
       -H "Content-Type: application/json" \
       -d '{"phone": "01-222-3333"}' \
       "https://api.fieldaware.net/user/57e226d06c6b455d9c1acff8e4cb714d"

.. sourcecode:: http

    HTTP/1.1 204 NO CONTENT
    Content-length: 0
    Connection: keep-alive


Authentication Failure
----------------------

When the API key is not supplied, the key is valid, or when the format of the header is not observed, requests fail with an ``HTTP 401 UNAUTHORIZED`` error. Depending on whether no API key was provided, or an invalid or malformed key, the exact error message may vary.

.. sourcecode:: bash

  curl -i \
     -H "Accept-Type: application/json" \
     https://api.fieldaware.net/user/0a7b345af6684fa58847920ee91a12bd

.. sourcecode:: bash

  > GET /user/0a7b345af6684fa58847920ee91a12bd HTTP/1.1
  > User-Agent: curl/7.37.1
  > Host: api.fieldaware.net
  > Accept: */*
  > Accept-Type: application/json
  >
  < HTTP/1.1 401 UNAUTHORIZED
  < Content-Type: application/json
  < WWW-Authenticate: Token
  < Content-Length: 86
  < Connection: keep-alive

  {
    "error": {
      "message": "Requires valid authentication",
      "name": "AuthenticationError"
    }
  }