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
| Route |
Method |
Description |
| /v0/reservations |
GET |
List scheduled reservations. |
| /v0/reservations/create |
POST |
Schedule a reservation. |
| /v0/reservations/{res_id} |
DELETE |
Delete a reservation from the schedule. |
| /v0/reservations/confirmations |
GET |
Enumerate pending reservations waiting to be started. |
| /v0/reservations/confirm |
POST |
Accept a pending reservation and start the timer. |
List Reservations
| Route |
Method |
Description |
| /v0/reservations |
GET |
List scheduled 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
| Route |
Method |
Description |
| /v0/reservations/create |
POST |
Schedule a reservation. |
Create a reservation at a fixed time in the future.
Parameters
"type" (string): The reservation type. One of:"fixed": A reservation at a fixed time."queued": A reservation for the next available time slot."quick_start": Try to create a 30 minute reservation starting now and fail if the reservation could not be started."device_address" (string): The unique identifier for a device. Consists of {device_id}@{hostname}, for example, "37deea48@proxy-us-mvo-5.headspin.io"."duration" (float): Desired reservation duration in units of seconds."start_time" (float): Desired reservation start time as a UNIX timestamp in seconds since the epoch."end_time" (float): 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: type, device_address
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: type, device_address, start_time, end_time
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: type, device_address, duration
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
| Route |
Method |
Description |
| /v0/reservations/{res_id} |
DELETE |
Delete a reservation from the schedule. |
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:
Get Reservations Pending Confirmation
| Route |
Method |
Description |
| /v0/reservations/confirmations |
GET |
Enumerate pending reservations waiting to be started. |
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
| Route |
Method |
Description |
| /v0/reservations/confirm |
POST |
Accept a pending reservation and start the timer. |
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:
