Introduction

This section provides an overview of APIs available in reserVie and how to use them. An API that allows you to get and send objects in reserVie.

Accessing API’s

Webhooks are current alpha and so available on a limited basis and strictly on request. Please submit your use case via a support ticket.

When accessing it is important to throttle the number of accesses to an API. Where an API exceeds the maximum number of requests, the system will invoke a throttle and will block all future requests over an extended period of time. Where accesses are excessive, our intelligent WAF may interpret accesses as a DOS and block future access. We recommend limiting API access to a maximum 4 per minute.

Limitations of API

reserVie serves APIs in real-time. However, we use a variety of data storage which make take time to sync. All storage will eventually synchronise, however this may up to a few minutes to complete.

Requirements of your client application

The following requirements are placed on the client application:

The requests must be via HTTPs.
The application must throttle access to the API within the limits specified.
Requests should be as application/json
Data is provided as JSON objects.

API overview

Security

To secure your API, we will offer you a private JWT (json web token) on registration of your client application. The JWT will be unique to you and your application and so it is important that you keep this information secret.

Upon accessing an API, you will be required to present the JWT in order to gain access to the associated requested resources.

reserVie uses the HTTP authentication scheme Authorization: Bearer <token> and as such will be included in the HTTP header. An example HTTP header for the API, will look as:

Authorization: Bearer 12434-232323-232323-2323

Content-Type: application/json

Content type

Currently the only content type that we support is application/json

API types

reserVie supports the following restful API’s:

GET - allows a resource to be fetched. If the resource is not specified, all resources will be be fetched
POST - creates a resource
PATCH - updates a resource
DELETE - deletes a resource.

Note GET, PATCH and DELETE are idempotent requests

URL

API’s are available via your unique reserVie URL using the eapi URI. For example, if your unique reserVie address was yoga-with-burty-smith.reservie.net, then access to the API would be via the following endpoint:

https://yoga-with-burty-smith.reservie.net/eapi/<resource>/[<id|null>]

API responses

The API supports the following response types:

200 - OK. Operation successful
201- Created OK
400 - Bad request. We received the request, but did not understand
401 - Authorization failed
404 - Request understood, but we were unable to locate the resource
405 - Method not allowed. The requested operation is not permitted for the associated resource
429 - Too many requests. Sent if the client application sends to many requests.
5xx - server error.

Resources and associated API

The reserVie API supports access to the following resources:

Customers - the customers associated to your account
Events - the events that are available for booking
Passes - Passes that are active in the system
CustomerPasses - the passes that have been allocated to a customer.

Customer

The customer object represents a customer that is registered to your account. reserVie supports the following endpoints:

GET - /eapi/customers
GET - /eapi/customers/:id
POST - /eapi/customers
PATCH - /eapi/customers/:id
DELETE - /eapi/cutomers/:id

The customer object

The customer object is as follows, this is

{
  "id": <integer>,
  "object": "customer",
  "firstname": <string>,
  "lastname": <string>,
  "email": <string>
  "mobile": <string>
  "active": true || false

}

Note: The password is write-only and is never returned with the API.

Retrieve a customer

To retrieve a specific customer, the following API should be used:

Endpoint: /eapi/customers/:id

HTTP Type: GET

Parameters: :id - the ID number of the customer. We recommend that you store this as a foreign key.

Returns:

{
  "id": 123,
  "object": "customer",
  "firstname": <string>,
  "lastname": <string>,
  "email": <string>
  "mobile": <string>
  "active": true || false
}

List all customers

To retrieve all customers, the following API should be used:

Endpoint: /eapi/customers

HTTP Type: GET

Parameters: null

Returns:

Returns a full list of all customer objects.

{
  "object": "customers",
  "data":[{
     "id": 123,
     "object": "customer",
     "firstname": <string>,
     "lastname": <string>,
     "email": <string>
     "mobile": <string>
     "active": true || false
  }]

}

Add a new Customer

To add a new customer, the following API should be used:

Endpoint: /eapi/customers

HTTP Type: POST

Parameters: Customer specification JSON object. The following parameters as expected:

{
  "firstname": <string>,
  "lastname": <string>,
  "password": <string>,
  "email": <string>
  "mobile": <string>

}

firstname - defines the first name of the customer

lastname - defines the last name of the customer

password - defines the password. This should be sent in clear text, reserVie will internally encrypt the password provided.

email - the email address of the customer

mobile - the contact number of the customer

Returns:

JSON customer object

{
  "id": 123,
  "object": "customer",
  "firstname": <string>,
  "lastname": <string>,
  "email": <string>
  "mobile": <string>
  "active": true
}

If the customer already exists, the operation will become idempotent

Update Customer

To retrieve a specific customer, the following API should be used:

Endpoint: /eapi/customers

HTTP Type: PATCH

Parameters: Customer specification JSON object. The following parameters as expected:

{
  "firstname": <string>,
  "lastname": <string>,
  "email": <string>
  "mobile": <string>
  "active": true

}

firstname - defines the first name of the customer

lastname - defines the last name of the customer

email - the email address of the customer

mobile - the contact number of the customer

Returns:

JSON customer object

{
  "id": 123,
  "object": "customer",
  "firstname": <string>,
  "lastname": <string>,
  "email": <string>
  "mobile": <string>
}

Delete a customer

To delete a specific customer, the following API should be used:

Endpoint: /eapi/customers/:id

HTTP Type: DELETE

Parameters: :id - the ID of the customer

Returns:

JSON customer object

{
  "id": 123,
  "object": "customer",
  "firstname": <string>,
  "lastname": <string>,
  "email": <string>
  "mobile": <string>
  "active": true
}

Customers are never actually deleted, but are instead archived. If you need a customer to be deleted due to a GDPR request by that customer, please contact us.

Event

The event object represents an event that is registered to your account. reserVie supports the following endpoints:

GET - /eapi/events/:date-start/:date-end
GET - /eapi/events/:id

The event object

The events object represents an event that is registered in the system.

{
  "id": <integer>,
  "object": "event",
  "name": <string>,
  "pricingoptions": [{
     "id": <string>,
     "object": "pricingoption",
     "name": <string>,
     "maxspace": <integer>,
     "price_float": <float>,
     "price_float_currency": <ISO string>,
     "price_credits": <integer>,
     "active": true || false
   }],
  "description": <string>,
  "type": <"virtual"> || <"physical">,
  "dates": [{
     "id": <string>,
     "object": "date",
     "bookings": [{
         "id": <string>,
         "object": "booking",
         "customer": <integer>,
         "spaces": <integer>,
         "option_id": <string>,
         "active": true || false
      }],
     "active": true || false
   }],
  "active": true || false
}

Retrieve an event

To retrieve an event, the following API should be used:

Endpoint: /eapi/events/:id

HTTP Type: GET

Parameters: :id - the ID number of the event. We recommend that you store this as a foreign key.

Returns:

Standard events object

{
  "id": <integer>,
  "object": "event",
  "name": <string>,
  "pricingoptions": [{
     "id": <string>,
     "object": "pricingoption",
     "name": <string>,
     "maxspace": <integer>,
     "price_float": <float>,
     "price_float_currency": <ISO string>,
     "price_credits": <integer>,
     "active": true || false
   }],
  "description": <string>,
  "type": <"virtual"> || <"physical">,
  "dates": [{
     "id": <string>,
     "object": "date",
     "bookings": [{
         "id": <string>,
         "object": "booking",
         "customer": <integer>,
         "spaces": <integer>,
         "option_id": <string>,
         "active": true || false
      }],
     "active": true || false
   }],
  "active": true || false
}

Retrieve all events within date range

To retrieve all events within a specific date range, the following API should be used:

Endpoint: /eapi/events/:date-start/:date-end

HTTP Type: GET

Parameters: :date-start - the start date of the look-up.

:date-end - the date-end

The :date-start and :date-end provides the date range of the look-up. All events that are scheduled within the date range will be returned. :date-start and :date-end should be provided in the following formats: YYYY-MM-DD, where:

Where YYYY is the century and year. For example 2021; MM is the month. For example January would be 01

Returns:

{
  "object": "events",
  "data": [{
      "id": <integer>,
      "object": "event",
      "name": <string>,
      "pricingoptions": [{
         "id": <string>,
         "object": "pricingoption",
         "name": <string>,
         "maxspace": <integer>,
         "price_float": <float>,
         "price_float_currency": <ISO string>,
         "price_credits": <integer>,
         "active": true || false
      }],
      "description": <string>,
      "type": <"virtual"> || <"physical">,
      "dates": [{
          "id": <string>,
          "object": "date",
          "bookings": [{
             "id": <string>,
             "object": "booking",
             "customer": <integer>,
             "spaces": <integer>,
             "option_id": <string>,
             "active": true || false
           }],
           "active": true || false
        }],
       "active": true || false
      }
   }]
}

Pass

The pass object represents a pass that is registered to your account. reserVie supports the following endpoints:

GET - /eapi/passes
GET - /eapi/passes/:id

The pass object

The pass object is as follows, this is

{
  "id": <integer>,
  "object": "pass",
  "name": <string>,
  "expires": <integer representing days>,
  "credits": <integer>
  "price_float": <string>
  "price_currency": <ISO string>

}

Retrieve a pass

To retrieve a pass object, the following API should be used:

Endpoint: /eapi/passes/:id

HTTP Type: GET

Parameters: :id - the ID number of the pass. We recommend that you store this as a foreign key.

Returns:

Standard events object

{
  "id": <integer>,
  "object": "pass",
  "name": <string>,
  "expires": <integer representing days>,
  "credits": <integer>
  "price_float": <string>
  "price_currency": <ISO string>
}

Retrieve all passes

To retrieve a pass object, the following API should be used:

Endpoint: /eapi/passes

HTTP Type: GET

Parameters: null

Returns:

Standard events object

{
  "object": "passes",
  "data": [{
     "id": <integer>,
     "object": "customer-pass",
     "name": <string>,
     "expires": <integer representing days>,
     "credits": <integer>
     "price_float": <string>
     "price_currency": <ISO string>
   }]
}

CustomerPass

The CustomerPasses object represents a pass that has been purchased. reserVie supports the following endpoints:

GET - /eapi/customer-passes
GET - /eapi/customer-passes/:search-type/:id - search types are ‘customer’ and ‘object’
- /eapi/customer-passes/customer/:id - searches for passes associated to a customer
- /eapi/customer-passes/object/:id - searches for passes with a matching ID.

The CustomerPass object

The CustomerPass object is as follows, this is

{
  "id": <integer>,
  "object": "customer-pass",
  "customer": <integer>,
  "pass": <integer>,
  "expires": <YYYY-MM-DD>,
  "credits_available": <integer>

}

Retrieve CustomerPass object(s) by customer ID

To retrieve a pass object, the following API should be used:

Endpoint: /eapi/customer-passes

HTTP Type: GET

Parameters: :search-type = customer and :id = customer ID.

Returns:

A list of customer pass objects

{
  "object": "customer-passes",
  "data": [{
     "id": <integer>,
     "object": "customer-pass",
     "customer": <integer>,
     "pass": <integer>,
     "expires": <YYYY-MM-DD>,
     "credits_available": <integer>
  }]

}

Retrieve CustomerPass object by object ID

To retrieve a pass object, the following API should be used:

Endpoint: /eapi/customer-passes

HTTP Type: GET

Parameters: :search-type = object and :id = customer ID.

Returns:

A list of customer pass objects

{
  "object": "customer-passes",
  "data": [{
     "id": <integer>,
     "object": "customer-pass",
     "customer": <integer>,
     "pass": <integer>,
     "expires": <YYYY-MM-DD>,
     "credits_available": <integer>
  }]

}

Retrieve all CustomerPass object(s)

To retrieve a pass object, the following API should be used:

Endpoint: /eapi/customer-passes

HTTP Type: GET

Parameters: null

Returns:

A list of customer pass objects

{
  "object": "customer-passes",
  "data": [{
     "id": <integer>,
     "object": "customer-pass",
     "customer": <integer>,
     "pass": <integer>,
     "expires": <YYYY-MM-DD>,
     "credits_available": <integer>
  }]

}