Getting started with the Spectrum Vanguard API

Authentication Context

Default Context

Authentication via the Daxko API gateway into Vanguard will often take place in the context of a service account. This means that, once a JWT token has been obtained via the authentication service, all requests will be served in the context of the default employee, site and workstation set up in the Daxko API gateway configuration.

In some instances — particularly GET requests — the context under which such requests are made is irrelevant. Examples of these may include:

Retrieving a list of sites for a club.
Getting details about an employee.

In other instances, however, the context under which these calls are made will have an effect on the results that are returned from a GET request or the data that is saved, updated or removed in POST, PUT and DELETE endpoints, respectively. Examples of these may include:

Checking in a member.
Logging the employee who updated the available slots for a tennis court.
Retrieving the availability for lockers at a given site.

These endpoints will not contain the site ID or employee ID in either the query string, the request body or the path, but such information is extracted from the authentication token.

Overriding the Default Context

In lieu of maintaining different sets of credentials and authentication tokens to switch between context, the Daxko API gateway provides the ability to override the default context by passing different headers with a requests. The values of these headers will supersede the values stored in an authentication token. The available headers are:

Header name	Value it overrides
`x-daxko-employeeid`	Logged-in employee ID.
`x-daxko-siteid`	Logged-in site ID.
`x-daxko-stationid`	Logged-in workstation ID.

A few details on these headers:

The headers are case-insensitive.
Not all of them need to be sent together, meaning that, if only the site needs to be overridden, the x-daxko-siteid header is the only one that needs to be sent.
Given the idempotent nature of the Daxko API, these headers must be sent with each requests that require the override. Sending it once will not result in subsequent requests being performed under the previous context.

An example of a request in which the site ID was overridden may look like the following:

bash
curl -X GET \
  https://api.partners.daxko.com/lockercategories/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <apikey>' \
  -H 'x-daxko-siteid: 1297'

Response Handling

This section explains the different response status codes that developers should expect from the Spectrum Vanguard API, as well as how response errors are handled and exposed.

Success Status Codes

Any response in the 2xx range should be considered a successful response. They may include:

Status code	Description
`200`	`OK`: This is the standard status codes for a successful response.
`201`	`Created`: Developers may receive this status code after certain `POST` requests, signifying that the entity being submitted to the API has been successfully created.
`202`	`Accepted`: This status can be expected under certain endpoints in which an asynchronous request has been acknowledged and enqueued for processing. This status is reserved for long-running operations or others that may provide fault tolerance via built-in retry policies, such as the completion of a contract.
`204`	`No content`: Developers may receive this status code after certain `PUT` or `DELETE` calls, in which the API will not respond with any content.

Error Response Codes

In the event of an unsuccessful request, the Spectrum Vanguard API will return any of the following status codes:

Status code	Description
`400`	`Bad request`: This status code alerts the developer that any part of the request — query string, body, path parameters — are invalid and should be retried.
`401`	`Unauthorized:` This status code signifies an invalid or expired JWT token, or invalid credentials when attempting to log in.
`403`	`Forbidden:` Receiving this status code signifies that, while a token may be valid, access to that particular resource is explicitly forbidden because of the user's scopes and roles.
`404`	`Not found`: This status code may tell the developer that either the endpoint cannot be found or that the particular resource (e.g., an employee when querying by ID) cannot be found.
`500`	`Internal server error`: This status code alerts the developer that an unhandled exception has ocurred when fulfilling the request.

Error Response Body

Consumers of the Spectrum Vanguard API should expect the following response body when an error is encountered, providing further context as to what happened.

{
    "Errors": [string array]
}

An example of a 400 status code response may look like so:

{
  "Errors": [
    "The member's first name is required",
    "The date of birth must be earlier than today."
  ]
}