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, a widely available command-line tool. We also use the jq tool to format any JSON output. There are other equally convenient tools available. For example, there are browser plugins such as RESTClient (Firefox), or Postman (Chrome), or standalone clients such as Fiddler, or rest-client. The process is in all cases the same.

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

curl -i https://api.fieldaware.net
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:

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:

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.

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

curl -i \
   -H "Accept-Type: application/json" \
   https://api.fieldaware.net/user/0a7b345af6684fa58847920ee91a12bd
> 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"
  }
}