BTXInteract.apib

FORMAT: 1A
HOST: https://test.btxinteract.com/api/

# BTX Interact

NOTE: The iOS networking stack will automatically cache content based on the HTTP caching headers.
It is important that these are sent to the client correctly.

Click on each of the requests to view the HTTP headers that need to be sent.

# Group Authentication

## Required Headers [/]

### Example [GET]

This section outlines the responses that could be returned from all endpoints that require authentication.

| Header        | Value                   | Description                                                                  |
|---------------|-------------------------|------------------------------------------------------------------------------|
| Authorization | Bearer <<access_token>> | The access token created from the GUID/DOB/DeviceID or RefreshToken/DeviceID |
| DeviceID      | <<device_id>>           | The DeviceID generated on the device, stored in the keychain.                |

When the app receives a 401 it should try to update the existing session using a refresh token.

+ Request

    + Headers
    
            Authorization: Bearer AFC306FA-2C91-4A00-BCB3-28BC406FEFA6
            DeviceID: 9677A0C8-4619-4993-A622-0CEAE4ECCCAA
     
+ Response 200 (text/plain)

            Not an actual endpoint, use the header fields for endpoints that require authentication.

+ Response 401 (application/json)
    
    + Attributes
        
        + Include Error
        + `reason_code`: `access_token_invalid`

## Sessions [/session]

### Create new session [POST]

+ Request (application/json)

    + Headers
        
            GUID: Patient GUID (from QR code)
            DeviceID: Generated UUID on device (stored in keychain)
    
    + Attributes
    
        + date_of_birth: `1996-05-16` (string, required) - The patient's date of birth

+ Response 201 (application/json)

    + Attributes
        
        + access_token: 4v45yv (string, required) - The access token used to authenicate short sessions.
        + refresh_token: 364346 (string, required) - The refresh token used to authenicate new sessions after expiry.

### Update existing session [PUT]

**NOTE:** If this returns a 401, the patient will need to re-pair the device with the account at the clinic.

+ Request (application/json)

    + Headers
        
            RefreshToken: Refresh token of an existing sessin (stored in keychain)
            DeviceID: Generated UUID on device (stored in keychain)
        
+ Response 201 (application/json)

    + Attributes
        
        + access_token: 4v45yv (string, required) - The access token used to authenicate short sessions.

+ Response 401 (application/json)

    + Attributes
        
        + Include Error
        + `reason_code`: `refresh_token_invalid`

# Group Patients

## Get Patient [/patient]

Patients is simple API to retrieve information about the patient.

### Retrieve the patient model [GET]

+ Request (application/json)
    
    + Headers
    
            Authorization: Bearer <<access_token>>
            DeviceID: <<device_id>

+ Response 200 (application/json)

    + Attributes (Patient)

## Patient Image [/patient/profile-image]

### Upload Profile Image [POST]

+ Request (multipart/form-data; boundary=---BOUNDARY)

        -----BOUNDARY
        Content-Disposition: form-data; name="image[file]"; filename="image.jpg"
        Content-Type: image/jpeg
        Content-Transfer-Encoding: base64

        /9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
        HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
        MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIA
        AhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEB
        AAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AD//Z
        -----BOUNDARY

+ Response 201

+ Response 413 (application/json)

    + Attributes
        
        + Include Error
        + title: The image was too big.
        + description: Please resize the image or select another image and try again.
        + `reason_code`: `validation_error`

+ Response 415 (application/json)

    + Attributes
        
        + Include Error
        + title: The image was of an unsupported type.
        + description: Please select another image and try again.
        + `reason_code`: `validation_error`

## Symptoms [/patient/symptoms/{id}]


### Get patient symptom entries [GET]

+ Request (application/json)
    
    + Headers
    
            Authorization: Bearer <<access_token>>
            DeviceID: <<device_id>

+ Response 200 (application/json)

    + Attributes (array)
        
        + (SymptomEntry)

### Create patient symptom entry [POST]

+ Request (application/json)

    + Headers
    
            Authorization: Bearer <<access_token>>
            DeviceID: <<device_id>
    
    + Attributes (SymptomEntry)
    
+ Response 201 (application/json)

    + Attributes (SymptomEntry)

+ Response 409 (application/json)

    + Attributes
    
        + Include Error
        + title: Entry conflict
        + description: `An entry with this date or ID already exists, you can delete this entry or change the date to another value.`
        + `reason_code`: conflict

+ Response 422 (application/json)

    + Attributes
    
        + Include Error
        + title: Validation error
        + description: `The date was invalid, try picking an earlier date.`
        + `reason_code`: `validation_error`

### Update patient symptom entry [PUT]

+ Request (application/json)

    + Headers
    
            Authorization: Bearer <<access_token>>
            DeviceID: <<device_id>
    
    + Attributes (SymptomEntry)
    
+ Response 200 (application/json)

    + Attributes (SymptomEntry)
    
+ Response 409 (application/json)

    + Attributes
    
        + Include Error
        + title: Entry conflict
        + description: `An entry with this date already exists, you can delete this entry or change the date to another value.`
        + `reason_code`: conflict

### Delete patient symptom entry [DELETE]

+ Parameters

    + id: `1B327DB6-286F-473E-B789-A2B0EA80EC6E` (string, required) - The UUID of the symptom entry, expected to conform to RFC 4122 version 4

+ Request (application/json)

    + Headers
    
            Authorization: Bearer <<access_token>>
            DeviceID: <<device_id>

+ Response 200

+ Response 404

## Medication [/patient/medication]

### Retrieve the medication information [GET]
    
+ Request

    + Headers
    
            Authorization: Bearer <<access_token>>
            DeviceID: <<device_id>
            
+ Response 200 (application/json)

    + Attributes (array)
        
        + (Medication)
    
# Group App Settings

## Legal [/legal]

### Retrieve the legal information [GET]

This API will **NOT** require the authentication headers.

+ Response 200 (application/json)

    + Attributes (Legal)

# Group Model Objects

Click on the array or dictionary name to see the details in Apiary when rendered.

# Data Structures

## Patient (object)
+ `first_name`: Brett (string, required) - The first name of the patient
+ `middle_name`: Trevor (string, optional) - The middle name of the patient
+ `last_name`: Best (string, required) - The last name of the patient
+ `profile_image_url`: https://url.to/an/image.jpg (string, optional) - The patient's profile image URL. JPG / PNG
+ `medication` (array[PartialMedication], required) - The medication the patient takes, partial models.
    
## SymptomEntry (object)
+ id: `1B327DB6-286F-473E-B789-A2B0EA80EC6E` (string, required) - UUID expected to conform to RFC 4122 version 4.
+ `created_at`: `2019-08-21T01:36:15+0000` (string, required) - When this entry was created, full ISO8601 datetime format: **yyyy-MM-dd'T'HH:mm:ssZ**
+ `updated_at`: `2019-08-21T01:57:28+0000` (string, required) - When this entry was created, full ISO8601 datetime format: **yyyy-MM-dd'T'HH:mm:ssZ**
+ date: `2019-08-21` (string, required) - The date this entry is for, full ISO8601 date format: **yyyy-MM-dd**
+ duration: 60 (number, required) - The duration in minutes between 0-1440, integer value.
+ severity: 5 (number, required) - The severity of the symptom between 0-10, integer value.
+ location (Location, optional) - The location of the symptom

## Location (object)
+ coordinate (LocationCoordinate, required) - The geographical coordinate information.
+ altitude: 250 (number, optional) - The altitude in meters, double value.
+ `floor_level`: 4 (number, optional) - The floor of a building on which the patient's device is located, integer value.
+ accuracy (LocationAccuracy, optional) - The location accuracy
+ speed: 2 (number, optional) - The instantaneous speed of the device, measured in meters per second. Double value.
+ course: 45 (number, optional) - The direction in which the device is traveling, measured in degrees and relative to due north. Double value.

## LocationCoordinate (object)
+ latitude: 5 (number, required) - The latitude in degrees, double value.
+ longitude: 10 (number, required) - The longitude in degrees, double value.

## LocationAccuracy (object)
+ horizontal: 200 (number, required) - The radius of uncertainty for the location, measured in meters. Double value.
+ vertical: 50 (number, required) - The accuracy of the altitude value, measured in meters. Double value.

## PartialMedication (object)
+ name: ADrugName (string, required) - The name of the medication
+ description: Used to treat headaches. (string, required) - A short description about the medication

## Medication (object)
+ name: ADrugName (string, required) - The name of the medication
+ description: Used to treat headaches. (string, required) - A short description about the medication
+ sections (array, required) - The sections to display. Support types: `text`, `image`, `video`
    + (object)
        + type: text (string, required) 
        + size: heading_small (string, required)
        + value: Text to be displayed as a small heading (string, required)
    + (object)
        + type: text (string, required) 
        + size: heading_medium (string, required)
        + value: Text to be displayed as a medium heading (string, required)
    + (object)
        + type: text (string, required)
        + size: heading_large (string, required)
        + value: Text to be displayed as a large heading (string, required)
    + (object)
        + type: text (string, required)
        + size: body (string, required)
        + value: Some text to be displayed to the patient (string, required)
    + (object)
        + type: image (string, required)
        + width: 600 (number, required) - The width of the image in pixels.
        + height: 400 (number, required) - The height of the image in pixels.
        + url: https://url.to/an/image.jpg (string, required)
    + (object)
        + type: video (string, required)
        + width: 600 (number, required) - The width of the video in pixels.
        + height: 600 (number, required) - The height of the video in pixels.
        + url: https://url.to/a/movie.mp4 (string, required)
        
## Legal (object)

+ `terms_and_conditions_url`: `https://test.btxinteract.com/api/terms_and_conditions` (string, required) - A URL to the Terms and Conditions
+ `privacy_policy_url`: `https://test.btxinteract.com/api/privacy_policy` (string, required) - A URL to the Privacy Policy
+ `support_url`: `https://test.btxinteract.com/api/support` (string, required) - A URL to contact support

## Error (object)

+ title: Short error title (string, required) - The title used to display to the patient
+ description: Short error description (string, required) - The error description to display to the patient
+ `reason_code` (enum[string], required) - The reason code for the error.
    + `access_token_invalid` (string) - The access token was invalid.
    + `refresh_token_invalid` (string) - The refresh token was invalid.
    + `validation_error` (string) - A validation error e.g. a field was too long
    + `conflict` (string) - An existing resource conflicts with a POST or PUT request.