Using Reservation API

Reservation API

Reservations provide a way to ensure a device is usable by a single user for a fixed duration starting at a given point in time. Normally, a device can be locked when it is free, but there is no guarantee that a specific device will be free at a given time. Reservations guarantee that a device will be free for the user that created the reservation. There are three types of reservations:

• Fixed - a reservation created for a future time with a predetermined duration
• Queued - a reservation created for the next available opening
• Quick start - an immediate reservation

A fixed reservation allows a user to schedule a reservation in the future, for example in 5 hours from now. A queued reservation allows a user to schedule a reservation for the next free slot that the device does not already have a reservation for. A quick start reservation is similar to a fixed reservation but is created for the current time.

Overview: Available API Routes

List Reservations

Sample request:

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/reservations 

Sample response:

{
    "09549615-f878-4849-8d95-69babb45b6c9": {
        "device_address": "ZY223P3W32@proxy-us-mvo-5.headspin.io",
        "user_id": "b66f560a-9272-417d-b449-3deb44b43999",
        "res_id": "09549615-f878-4849-8d95-69babb45b6c9",
        "start_time": 1639010164.422,
        "end_time": 1639013764.422,
        "confirmation_status": "confirmed",
        "type": "queued"
    }
}

Create a Reservation

Create a reservation at a fixed time in the future.

Parameters

• <code class="dcode">"type" (string)</code>: The reservation type. One of:
• <code class="dcode">"fixed"</code>: A reservation at a fixed time.
• <code class="dcode">"queued"</code>: A reservation for the next available time slot.
• <code class="dcode">"quick_start"</code>: Try to create a 30 minute reservation starting now and fail if the reservation could not be started.
• <code class="dcode">"device_address" (string)</code>: The unique identifier for a device. Consists of <code class="dcode">{device_id}@{hostname}</code>, for example, <code class="dcode">"37deea48@proxy-us-mvo-5.headspin.io"</code>.
• <code class="Dcode">"duration" (float)</code>: Desired reservation duration in units of seconds.
• <code class="dcode">"start_time" (float)</code>: Desired reservation start time as a UNIX timestamp in seconds since the epoch.
• <code class="dcode">"end_time" (float)</code>: Desired reservation end time as a UNIX timestamp in seconds since the epoch.

Create a Quick Start Reservation

A quick start reservation attempts to immediately start a reservation for 30 minutes and fails if this cannot be achieved.

Required arguments: <code class="dcode">type</code>, <code class="dcode">device_address</code>

Sample request:

curl -X POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/reservations/create -d '{"type": "quick_start", "device_address": "37deea48@proxy-us-mvo-5.headspin.io"}' 

Sample response:

{
    "reservation": {
        "device_address": "37deea48@proxy-us-mvo-5.headspin.io",
        "user_id": "b66f560a-9272-417d-b449-3deb44b43999",
        "res_id": "e83f7d07-ae32-4a38-8984-fa352e849bb0",
        "confirmation_status": "confirmed",
        "start_time": 1639021681.922,
        "end_time": 1639023481.922,
        "type": "quick_start"
    },
    "success": true
}

Create a Fixed Reservation

Schedule a reservation in the future.

Required arguments: <code class="dcode">type</code>, <code class="dcode">device_address</code>, <code class="dcode">start_time</code>, <code class="dcode">end_time</code>

Sample request to schedule a 10 minute reservation:

curl -X POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/reservations/create -d '{"type": "fixed", "device_address": "37deea48@proxy-us-mvo-5.headspin.io", "start_time": 1639026327.188917, "end_time": 1639026667.248011}' 

Sample response:

{
    "reservation": {
        "device_address": "37deea48@proxy-us-mvo-5.headspin.io",
        "user_id": "b66f560a-9272-417d-b449-3deb44b43999",
        "res_id": "e4ac696f-450f-4d1f-aba1-d727f417f15c",
        "start_time": 1639026327.189,
        "end_time": 1639026667.248,
        "confirmation_status": "confirmed",
        "type": "fixed"
    },
    "success": true
}

Create a Queued Reservation

Queued-type reservations are added to a queue if a reservation is currently active on the targeted device. Queued reservations must be confirmed within 5 minutes of the start time

Required arguments: <code class="dcode">type</code>, <code class="dcode">device_address</code>, <code class="dcode">duration</code>

Sample request:

curl -X POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/reservations/create -d '{"type": "queued", "device_address": "37deea48@proxy-us-mvo-5.headspin.io", "duration": 3600}' 

Sample response:

{
    "reservation": {
        "device_address": "37deea48@proxy-us-mvo-5.headspin.io",
        "user_id": "b66f560a-9272-417d-b449-3deb44b43999",
        "res_id": "b04d2718-6183-49f4-b1b7-74982347ab33",
        "start_time": 1639025990.991,
        "end_time": 1639029590.991,
        "confirmation_status": "unconfirmed",
        "type": "queued"
    },
    "success": true
}

Delete a Reservation

Delete a reservation whether active or pending.

Sample request:

curl -X DELETE -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/reservations/b04d2718-6183-49f4-b1b7-74982347ab33 

Sample response:

{"success": true}

Get Reservations Pending Confirmation

Enumerate reservations waiting on confirmation to begin. Note that the type of the reservation returned will always be queued.

Sample request:

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/reservations/confirmations 

Sample response:

{
  "b04d2718-6183-49f4-b1b7-74982347ab33": {
    "confirmation_end_time": 1639025524.552,
    "confirmation_status": "awaiting_confirmation",
    "user_id": "b66f560a-9272-417d-b449-3deb44b43999"
  }
}

Confirm a Pending Reservation

Confirm a reservation to start the reservation period.

Sample request:

curl -X POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/reservations/b04d2718-6183-49f4-b1b7-74982347ab33/confirm 

Sample response:

{"success": true}