REST API version 1

This REST API is for managing an intervention as a whole. A key provides API access to all participants and so it is not suitable for participant devices to hold the key. For that scenario, see Participant API version 1 for the API that provides access to a specific participant.

LifeGuide provides a REST API to manage parts of an intervention. The API follows the GitHub API specification where possible.

To obtain an API key, go to your intervention and then click on "Configure API keys" and then "New API Key".

REST API endpoints

Intervention Users (participants)

List Intervention Users

Example cURL command:

curl -i -X GET \
    --header "Authorization: Token cOrNDlXtHTH17lFYUF5ixo8e5w7myXxM" \
    "https://lifeguideonline.org/api/v1/intervention_user?per_page=5"

Example response:

HTTP/1.1 200 OK
Date: Mon, 01 Jan 2018 00:00:00 GMT
Server: Apache-Coyote/1.1
X-Total: 13
Link: <https://lifeguideonline.org/api/v1/intervention_user?page=2&per_page=5>; rel="next"
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked

[{ "id": 1, "enabled": true, "username": "username1", "uri": "https://lifeguideonline.org/api/v1/intervention_user/1"},
 { "id": 2, "enabled": true, "username": "username2", "uri": "https://lifeguideonline.org/api/v1/intervention_user/2"},
 { "id": 3, "enabled": true, "username": "username3", "uri": "https://lifeguideonline.org/api/v1/intervention_user/3"},
 { "id": 4, "enabled": true, "username": "username4", "uri": "https://lifeguideonline.org/api/v1/intervention_user/4"},
 { "id": 5, "enabled": true, "username": "username5", "uri": "https://lifeguideonline.org/api/v1/intervention_user/5"}]

Create an Intervention User

Example cURL command:

curl -i -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Token cOrNDlXtHTH17lFYUF5ixo8e5w7myXxM" \
    --data '{"username"="john.smith","password"="123456"}' \
    "https://lifeguideonline.org/api/v1/intervention_user"

Example response:

HTTP/1.1 201 Created
Date: Mon, 01 Jan 2018 00:00:00 GMT
Server: Apache-Coyote/1.1
Content-Location: https://lifeguideonline.org/api/v1/intervention_user/20
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked

Delete an Intervention User

Example cURL command:

curl -i -X DELETE \
    --header "Authorization: Token cOrNDlXtHTH17lFYUF5ixo8e5w7myXxM" \
    "https://lifeguideonline.org/api/v1/intervention_user/20"

Example response:

HTTP/1.1 204 No Content
Date: Mon, 01 Jan 2018 00:00:00 GMT
Server: Apache-Coyote/1.1
Content-Type: text/html;charset=utf-8
Content-Length: 0

Intervention User Data

List Intervention User Data

Example cURL command:

curl -i -X GET \
    --header "Authorization: Token cOrNDlXtHTH17lFYUF5ixo8e5w7myXxM" \
    "https://lifeguideonline.org/api/v1/intervention_user/2/data"

Example response:

HTTP/1.1 200 OK
Date: Mon, 01 Jan 2018 00:00:00 GMT
Server: Apache-Coyote/1.1
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked

{
  "variable1": "value1",
  "variable2": "value2",
  "variable3": "value3",
  "variable4": 4,
  "variable5": 5,
  "variable6": 6
}

Create / Update Intervention User Data

You can create user data as follows. Please note that the data must be specified using JSON and so that strings must be enclosed in double quotes.

Example cURL command:

curl -i -X PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Token cOrNDlXtHTH17lFYUF5ixo8e5w7myXxM" \
    --data '"string value"' \
    "https://lifeguideonline.org/api/v1/intervention_user/2/data/variable1"

Example response:

HTTP/1.1 204 No Content
Date: Mon, 01 Jan 2018 00:00:00 GMT
Server: Apache-Coyote/1.1
Content-Location: https://lifeguideonline.org/api/v1/intervention_user/2/data/variable1
Content-Type: text/html;charset=utf-8

Read Intervention User Data

Example cURL command:

curl -i -X GET \
    --header "Authorization: Token cOrNDlXtHTH17lFYUF5ixo8e5w7myXxM" \
    "https://lifeguideonline.org/api/v1/intervention_user/2/data/variable1"

Example response:

HTTP/1.1 200 OK
Date: Mon, 01 Jan 2018 00:00:00 GMT
Server: Apache-Coyote/1.1
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked

{
  "variable1": "value1"
}

Messages

List of Messages

Example cURL command:

curl -i -X GET \
    --header "Authorization: Token cOrNDlXtHTH17lFYUF5ixo8e5w7myXxM" \
    "https://lifeguideonline.org/api/v1/messagebox/mailto:person@example.com/message"

Example response:

[
  {
    "uri": "https://lifeguideonline.org/api/v1/messagebox/mailto:person@example.com/message/14"
    "id": 14,
    "body": "Content",
    "groupId": "group1",
    "dateToSend": "2018-05-16T23:11:42Z",
    "address": "mailto:person@example.com",
    "subject": "Subject",
    "sentDate": "2018-05-16T23:15:00Z",
  },
  
  ...
]

Delete a Message

Example cURL command:

curl -i -X DELETE \
    --header "Authorization: Token cOrNDlXtHTH17lFYUF5ixo8e5w7myXxM" \
    "https://lifeguideonline.org/api/v1/messagebox/mailto:person@example.com/message/14"

Example response:

HTTP/1.1 204 No Content
Date: Mon, 01 Jan 2018 00:00:00 GMT
Server: Apache-Coyote/1.1
Content-Type: text/html;charset=utf-8
Content-Length: 0

Notes

Pagination

For endpoints that support pagination, the following query arguments are used to control pagination:

Parameter	Description
page	The page of results to return. This starts at 1.
per_page	The number of results per page. Default is 100.

The total number of results is returned in the X-Total header of the response.

Dates

Dates are expressed without timezones. The following ISO-8601 format is used:

2018-05-16T23:15:00Z

Error responses

For create and update operations that fail internal validation tests, the LifeGuide REST API will return a status code of 400 with a JSON formatted error object, e.g.:

{
  "errors":
  [
    {
      "field": "username",
      "validation": "unique",
      "value": "john.smith"
    }
  ]
}

Each error has three fields:

• field is the name of the field with the validation error.
• validation is the type of validation test that failed. Known values are "unique" for fields that are set to be unique and "blank" for fields that must have a value.
• value is the value that was given in the request.