docs.apib

FORMAT: 1A
HOST: http://35.177.199.115/development

# FloBot Server API
This document outlines the routes for the FloBot web server, stored on AWS. Most routes require the user to be authenticated.
Authentication is checked by validating the bearer token in `Authorization` header.

# Data Structures

## Delivery
+ id: `23` (required, number)
+ state (enum) - Represents the state of the delivery
    + IN_QUEUE - Delivery has not been started
    + MOVING_TO_SOURCE - Robot is in transit to source target
    + AWAITING_AUTHENTICATION_SENDER - Robot is waiting for the sender to authenticate
    + AWAITING_PACKAGE_LOAD - Robot is awaiting the sender to signal they are done loading the package
    + PACKAGE_LOAD_COMPLETE - Sender has signalled they are done loading the package
    + MOVING_TO_DESTINATION - Robot is in transit to destination target
    + AWAITING_AUTHENTICATION_RECEIVER - Robot is waiting for the receiver to authenticate
    + AWAITING_PACKAGE_RETRIEVAL - Robot is awaiting the receiver to signal they are done picking up the package
    + PACKAGE_RETRIEVAL_COMPLETE - Receiver has signalled they are done picking up the package
    + COMPLETE - Delivery has been completed
    + UNKNOWN - Error state
+ priority: `0` (number, required)
+ from (required, Target)
+ to (required, Target)
+ sender: `jdoe` (required, string)
+ receiver: `drseuss` (required, string)
+ packageList (array[Package])
+ robot: `0` (number) - Once the delivery is underway, this contains the robot it has been assigned to.

## UserCore
+ username: `jsmith` (required, string)

## PackageCore
+ name: `Blood sample` (required, string)
+ description: `Blood sample for patient Jane Doe` (string)
+ priority: 0 (number, required) - The lower, the higher the priority

## Package (PackageCore)
+ id: `11` (required, number)

## Target
+ id: `54` (required, number) - ID of the target
+ name: `Reception` (required, string) - Name of the target
+ description: `The first-floor reception in Block A` (string) - Description of the target
+ color: `red` (required, nullable) - Color of the target

## BadRequestError
+ code: `400` (number, required)
+ error: `Your request is malformed` (string, required)

## UnauthenticatedError
+ code: `401` (number, required)
+ error: `You must authenticate in order to access this resource` (string, required)

## ForbiddenError
+ code: `403` (number, required)
+ error: `You do not have permission to access this resource` (string, required)

## NoResourceError
+ code: `404` (number, required)
+ error: `The requested resource does not exist` (string, required)

# Group Deliveries
This resource group exposes the routes required by the app to access, modify, create and delete deliveries.

## All deliveries [/deliveries]
This resource collects data on deliveries.

### Gets list of deliveries [GET]

+ Response 200

      + Attributes (array[Delivery])

### Creates a delivery [POST]

This request takes in the IDs for the source and destination Targets and creates
a new delivery in the server.

The user must provide a valid bearer token, matching the sender's currently active token,
to submit a delivery.

The server responds with the newly created package object.

+ Request

      + Headers

            Authorization: Bearer 8aHjr65ULEZItDm7eEeoHwO55CDnbgdJ

      + Attributes (PackageCore)
          + from: `23` (required, number) - ID of departure Target
          + to: `12` (required, number) - ID of arrival Target
          + sender: `jdoe` (required, string) - Username of sender User
          + receiver: `drseuss` (required, string) - Username of receiver User

+ Response 200

      + Attributes (Delivery)

+ Response 400

      + Attributes (BadRequestError)
          + friendly: `There's no user with that username`

+ Response 403

      + Attributes (ForbiddenError)
          + friendly: `The sender has to be yourself`

### Clear queue [DELETE]

+ Response 200

## Delivery [/delivery/{id}]

+ Parameters
    + id: `12` - ID of the delivery object being retrieved

### Get delivery information [GET]

+ Response 200

      + Attributes (Delivery)

+ Response 404

      + Attributes (BadRequestError)
          + friendly: `There's no delivery with that ID!`

### Partially update delivery [PATCH]
Partially updates the resource, replacing the supplied fields with the new ones.

Valid fields to update are: `state`.

+ Request for a delivery in queue that is now underway

      + Attributes
          + state: `MOVING_TO_SOURCE`
          + robot: `0`

+ Request for other patches, except authentications

      + Attributes
          + state: `MOVING_TO_SOURCE`
          + robot: `0`

+ Response 200

      + Attributes (Delivery)

+ Response 400

      + Attributes (BadRequestError)
          + friendly: `This robot is already delivering something.`

+ Response 403

      + Attributes (ForbiddenError)
          + friendly: `Illegal state transition attempted.`

+ Response 404

      + Attributes (NoResourceError)
          + friendly: `There's no delivery with that ID!`

### Delete delivery [DELETE]

+ Response 200

+ Response 404

      + Attributes (BadRequestError)
          + friendly: `There's no delivery with that ID!`

# Group Users
This resource group exposes the routes required by the app to obtain the user list.

## All users [/users]
This resource collects data on the whole collection of users.

### Gets list of users [GET]

+ Response 200

      + Attributes (array[UserCore])

# Group Targets

## Targets [/targets]

### Get all targets [GET]

+ Response 200

    + Attributes (array[Target])

### Add target [POST]

+ Request

    + Attributes
        + name: `Dr. Jack's office` (string, required)
        + description (string, nullable)
        + color: `red` (string)

+ Response 200

    + Attributes (array[Target])

+ Response 400

    + Attributes (BadRequestError)
        + friendly: `Target information is badly formatted`

### Clear targets [DELETE]

+ Response 200

## Target [/target/{id}]

+ Parameters
    + id: `4` - ID of target

### Retrieve target [GET]

+ Response 200

    + Attributes (array[Target])

+ Response 404

    + Attributes (NoResourceError)
        + friendly: `This target does not exist`

### Partially update target [PATCH]

+ Request update colour mapping

    + Attributes
        + color: `red` (string)

+ Response 200

    + Attributes (Target)

+ Response 400

    + Attributes (BadRequestError)
        + friendly: `Target information is badly formatted`

+ Response 404

    + Attributes (NoResourceError)
        + friendly: `This target does not exist`

### Delete target [DELETE]

+ Response 200

+ Response 404

    + Attributes (NoResourceError)
        + friendly: `This target does not exist`

# Group Authentication

## Login [/login]
Allows the user to login. Returns a bearer token if successful.

### POST

+ Request

      + Attributes
          + username: `jdoe` (required, string)
          + password: `password123` (required, string)

+ Response 200

      + Attributes
          + bearer: `c6e1f9d0-a241-4e29-8baa-2625f1e3a779`

+ Response 401

      + Attributes (UnauthenticatedError)
          + friendly: `Incorrect user/password combination`

## Register [/register]
Allows the user to register. Returns a bearer token if successful.

### POST

+ Request

      + Attributes
          + username: `jdoe` (required, string)
          + name: `Dr. John Doe` (required, string)
          + password: `password123` (required, string)

+ Response 200

      + Attributes
          + bearer: `c6e1f9d0-a241-4e29-8baa-2625f1e3a779`

+ Response 401

      + Attributes (UnauthenticatedError)
          + friendly: `Incorrect user/password combination`

# Group Robot
This resource group exposes the required routes for the vision system to interface with the robot. All robot routes require passing a robot ID. In the current system, there's only one robot available (ID 0).

## Batch updates [/robot/{robotid}/batch]

### Batch retrieval [GET]
Makes a single, batch retrieval of all robot fields. This route is mean to avoid the overhead of two requests being issued by the robot, seeing that it has very limited connectivity capabilities.

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Response 200

    + Attributes
        + angle: `50.0`
        + correction: `4.5`
        + motor: true
        + distance: `250.0`
        + delivery - Shown only if the robot is currently tasked with transporting a delivery
            + senderAuthToken: `GgkWGPKyCz` - The QR token that is shown to the sender for authentication
            + receiverAuthToken: `5wx7kAhRaY` - The QR token that is shown to the receiver for authentication
            + state: `MOVING_TO_SOURCE` - Current state of the delivery object the robot is carrying. The robot can monitor this so it knows when it should show the QR (and which one it should show)

### Batch update [POST]
Makes a batch update on some of the robots fields. Fields that can be updated in this way are: `correction`, `angle`, `motor` and `distance`.

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Request with a single field

    + Attributes
        + angle: `50.0`

+ Request with all fields

    + Attributes
        + angle: `50.0`
        + correction: `4.5`
        + motor: true
        + distance: `250.0`

+ Response 200

    + Attributes
        + angle: `50.0`
        + correction: `4.5`
        + motor: true
        + distance: `250.0`
        + delivery - Shown only if the robot is currently tasked with transporting a delivery
            + senderAuthToken: `GgkWGPKyCz` - The QR token that is shown to the sender for authentication
            + receiverAuthToken: `5wx7kAhRaY` - The QR token that is shown to the receiver for authentication
            + state: `MOVING_TO_SOURCE` - Current state of the delivery object the robot is carrying. The robot can monitor this so it knows when it should show the QR (and which one it should show)

## Correction [/robot/{robotid}/correction]
Exposes a mechanism to issue angle corrections to the robot.

### Retrieve correction [GET]

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Response 200

    + Attributes
        + correction: `4.5`

### Issue a correction [POST]
Issues a new correction to the angle of the robot. If a correction has already been issued, returns an error.

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Request

    + Attributes
        + correction: `4.5`

+ Response 200

    + Attributes
        + correction: `4.5`

+ Response 400

    + Attributes (BadRequestError)
        + friendly: `Invalid correction angle.`

## Angle [/robot/{robotid}/angle]
Exposes a mechanism to issue angles to the robot.

### Retrieve angle [GET]

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Response 200

    + Attributes
        + angle: `100.0`

### Issue an angle [POST]

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Request

    + Attributes
        + angle: `100.0`

+ Response 200

    + Attributes
        + angle: `100.0`

+ Response 400

    + Attributes (BadRequestError)
        + friendly: `Invalid angle supplied.`

## Distance [/robot/{robotid}/distance]
Exposes a mechanism to issue moving distances to the robot.

### Retrieve distance [GET]

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Response 200

    + Attributes
        + distance: `40.0`

### Issue a distance [POST]

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Request

    + Attributes
        + distance: `40.0`

+ Response 200

    + Attributes
        + distance: `40.0`

+ Response 400

    + Attributes (BadRequestError)
        + friendly: `Invalid distance supplied.`

## Motor [/robot/{robotid}/motor]
Exposes a mechanism to turn the robot on and off.

### Retrieve motor state [GET]

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Response 200

    + Attributes
        + motor: false

### Issue a new motor state [POST]

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Request

    + Attributes
        + motor: true

+ Response 200

    + Attributes
        + motor: true

+ Response 400

    + Attributes (BadRequestError)
        + friendly: `Invalid motor state supplied.`

## Locking [/robot/{robotid}/lock]
Exposes the state of the locking mechanism, for reading or modification.

### Gets lock state [GET]

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Response 200

    + Attributes
        + lock: `false` - Boolean value indicating whether the lock is engaged.

### Updates the lock state [POST]

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Request

    + Attributes
        + lock: `false` - Boolean value indicating whether the lock is engaged.

+ Response 200

    + Attributes
        + lock: `false` - Boolean value indicating whether the lock is engaged.

## Verify [/robot/{robotid}/verify]
This resource exposes the QR verification challenge route.

### Send challenge [POST]
This route sends the token read from the QR code alongside a bearer token in the authorization
header.

+ Parameters
    + robotid: `0` (number, required) - ID of the robot

+ Request with challenge token

    + Headers

            Authorization: Bearer 8aHjr65ULEZItDm7eEeoHwO55CDnbgdJ

    + Attributes
        + token: `4qMNg0gToH`

+ Response 200

+ Response 400

    + Attributes (BadRequestError)
        + friendly: `Invalid delivery state`

+ Response 403

    + Attributes(ForbiddenError)
        + friendly: `Challenge failed. Check your bearer and challenge tokens`