Introduction

This specification defines API Blueprint for the "Guest pass" functionallity. The methods and data models in this specification should serve as a blueprint that can be implemented by member management systems to allow for an easy connection of EGYM platform to their systems. So, this is not an API specification of an API on EGYM's servers. EGYM can, however, also adapt to other methods and data structures. However, there are limitations on the supported authentication approaches (only API key authentication, no single-user authorization) as well as to the nature of the supported API architectures (only backend-to-backend APIs are supported, so API calls can be done in the background and without authentication of each single user).

More on why these limitations exist can be found in the API Overview where we also explain the data privacy concept behind this decision.

What this API is about

The Guest Pass API should provide access to the creation of gues passes. A typical use-case is to allow prospect customers to visit the gym for some limited amount of time. With a proper integration into the MMS, we can make sure that the checkin experience is smooth in these cases.

API architecture requirements

This API needs to be impleneted for a server-to-server use-case. That means: Authentication needs to be done on a per-gym level (or per-location/per-chain), but not on a per user level with individual logins. The reason for the architecture choice is rooted in the data privacy model: we are operating on "gym data" which belongs to the gym and not to an individual user as per our definition of the data privacy model. This allows us to also implement use-cases where e.g. a trainer would manage pieces of this information from the EGYM trainer app on the user's behalf.

General API Contracts

Authentication

This API uses token-based authorization only while the level of authentication may differ e.g. single a single token for a gym chain, or a gym location/individual club.

Authentication HTTP Headers

There are several standard HTTP Headers listed below that may be used and can easily be configured in order to provide authentication data to every operation.

X-Chain-ID

This header provides ID of a Chain which we access in canonical operation.

Required for every canonical operaiton based on Chain information (security, configuration etc.)

Possible reasons of validation errors:

• missing => 400
• invalid => 401

X-Chain-Secret

This header provides chain-level secret ("API key") correspondent to the chain ID defined in X-Chain-ID header.

Required if API expects access tokens Chain level.

X-Location-ID

This header provides ID of a Location which we access in canonical operation. Required for every canonical operaiton based on Location information (security, configuration etc.)

Possible reasons of validation errors:

• missing => 400
• invalid => 401

X-Location-Secret

This header provides location-level secret correspondent to Location ID defined in X-Location-ID header. Required if API expects access tokens on Location level.

X-Client-Secret

This header contains the Client Secret. It is a credential to access API in scope of specific Partner implementation. It is required for every canonical operation which supports API access restriction on Partner level.

Possible reasons of validation errors:

• missing => 400
• invalid => 401

X-User-ID

This header provides ID of a user which is accessing his/her data.

Possible reasons of validation errors:

• missing => 400
• invalid => 401

Date Format

All dates in the API are strings in ISO 8601 format and in UTC time zone:

Valid example:

Invalid examples:

Errors

Conventional HTTP response codes are used to indicate the success or failure of an API request.

General Requirements:

• Every error response has field message.
• Every error response has field cause.
  • There are standard causes associated with corresponding HTTP status codes (4xx, 5xx).
  • And there might be also custom causes always defined on operation level and associated with 422 status code.

400: Bad Request

Cause is badRequest. This cause is used for all parameter-level validation errors. This is often due to missing a required parameter or wrong parameter format. This can be also due to violation of some contract defined in the given specification for a certain parameter.

Requirements:

• Error message can simply contain "Bad Request"
• Additional field errors must be present, which is a map of pairs: "<parameterName>": "<reason>". See example.
• Parameter names are defined in the documentation of respective canonical operations.
• Possible reasons are defined in the documentation of parameters of respective canonical operations.

Example:

401: Unauthorized Access

Cause is unauthorizedAccess. Bad, unexpected or expired access data (see 'Authentication HTTP Headers': X-Client-Secret, X-Chain-ID/X-Chain-Secret, X-Location-ID/X-Location-Secret).

Requirements:

• Error message must clearly indicate the reason of the failure and what is expected to fix it.
• Additional field accessLevel must indicate the level of access requested that caused this error (i.e. level of access backed by correspondent access headers): client, chain, or location.

Suggested action: Fix access data and then retry.

Example:

404: Entity Not Found

Cause is entityNotFound. Any referenced entity or resource is not found.

Requirements:

• Error message must clearly indicate the reason of the failure.
• Additional field parameter must be present. Parameter indicates which parameter of the request has wrong value that was not found. This parameter is then indicated in the documentation of respective canonical operation in section "Possible reasons of validation errors".

Example:

404: Resource Not Found

Cause is resourceNotFound. The requested endpoint does not exist or is not supported.

Example:

405: Method Not Allowed

Used HTTP method is not supported for the given endpoint. For example, POST, PUT, DELETE, etc.  

422: Custom Cause

The request was well-formed but could not be completed due to failed server-side validation checks, which can't be performed by client without server calls.

This error can be used only if it is specified on operation level. Requirements:

• Error message must clearly indicate the reason of the failure.
• Additional field cause must indicate what exactly has caused this error.
• Additional field reason must indicate the reason of the failure and is logically bound to the cause by extending it.
• The values for cause and reason must be strictly defined at operation level. The values that are not defined at operation level must never be used.

Example:

429: Too Many Requests

Cause is rateLimitsExceeded. Too many requests hit the API too quickly (Rate limit exceeded).

Example:

500: Internal Server Error

Cause is internalUnexpectedError. An unexpected error occurred while processing the request. Suggested action: Use exponential backoff.

Detailed reason of internal server error is usually not returned in response to the client. Detailed reason (error stack trace) must be logged in internal logging system.

Example: