REST API version 1

LifeGuide provides a REST API to manage parts of an intervention. This API is a work-in-progress and so will not be complete. The API follows the GitHub API specification where possible.

The REST API is not deployed on the live servers yet! It is available for testing on https://beta.lifeguideonline.org/

REST API endpoints

Intervention Users (participants)

List Intervention Users

Example cURL command:

curl -i -X GET \
    --header "Authorization: Token cOrNDlXtHTH17lFYUF5ixo8e5w7myXxM" \
    "https://beta.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://beta.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://beta.lifeguideonline.org/api/v1/intervention_user/1"},
 { "id": 2, "enabled": true, "username": "username2", "uri": "https://beta.lifeguideonline.org/api/v1/intervention_user/2"},
 { "id": 3, "enabled": true, "username": "username3", "uri": "https://beta.lifeguideonline.org/api/v1/intervention_user/3"},
 { "id": 4, "enabled": true, "username": "username4", "uri": "https://beta.lifeguideonline.org/api/v1/intervention_user/4"},
 { "id": 5, "enabled": true, "username": "username5", "uri": "https://beta.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://beta.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://beta.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://beta.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://beta.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://beta.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://beta.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://beta.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://beta.lifeguideonline.org/api/v1/messagebox/mailto:person@example.com/message"

Example response:

[
  {
    "uri": "https://beta.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://beta.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.