Version 2.0 of PerfectGym API

PerfectGym system is growing very fast. We are developing new features on a daily basis,
adapting to new markets and covering more and more business models.

This is why, we’ve finally decided to redesign our API, to be faster and more flexible.
We are proud to introduce it to the public.

How it’s different than v1?

We want to introduce consistent approach based on concept of CQRS (Command-Query responsibility separation).
This means, that we threat querying and modifying data separately:

  • for basic data queries we use OData standard (more on the topic below) - this is the query part
  • for modifying data (and sometimes for more specific data queries), we use standard POST endpoints - this is the command part
  • use JsonPatch syntax for changing only the selected values of a resource

This means, that we don’t try to be fully REST-ful, which we decided is not good approach for our growing needs.

New API version is still under intensive development

This means that it is not as fully featured as the old one.
Despite this, we want it to be already available, because we believe this would benefit our customers.

Deprecation & compatibility info

Eventually we would want to deprecate the old API, but this won’t happen any soon.
Too many of our customers rely on it on a daily basis, and we cannot leave them without support.

However, we are not going to add new features to the older API. This way migration to new version is going to be natural.

For any new development we reccommend you to use API v2 wherever possible, falling back to the older one when needed.
You can use them at the same time without any problems.
Authentication method described here works for v1 as well.

Translations

Some properties returned by the API endpoints as well as error messages are translatable.
For instance a trainer bio can be translated into multiple languages. By default API V2 will look for a translation in your company's primary language.
However, you can request a specific language by using an Accept-Language header. Here's an example:

1
Accept-Language: da, en-gb;q=0.8, en;q=0.7
You can read more about this here: https://datatracker.ietf.org/doc/html/rfc2616#page-104

What is OData?

OData is open data transfer standard. It is in some ways similar to more widely known GraphQL.
If you ever used any kind of ORM library, you can see OData as a kind of ORM through HTTP.

In practice, that means, that if you want to query members, you would make a request:

1
GET /api/v2/odata/Members

There is an entity called Member, and you can query it by calling it’s endpoint.

But there is more, you can for example query members, whose first name is John:

1
GET /api/v2/odata/Members?$filter=firstName eq 'John'

If you want to search by phone number or any other field containing '+' sign you need to replace '+' with the code of this character: '%2B':

1
GET /api/v2/odata/Members?$phoneNumber eq '%2B48501456123'

Your members are assigned to some club, which is their home club. You may want to pull that clubs’ data along with the member info.
With OData it’s easy:

1
GET /api/v2/odata/Members?$filter=firstName eq 'John'&$expand=homeClub

With OData you can also build very complicated queries.
Here is a query that retrieves first 100 of not deleted payment plans available in club with ID=1:

1
GET /api/v2/odata/PaymentPlans?$top=100&$filter=isDeleted eq false and availableInClubs/any(c: c/id eq 1)

OData syntax is very rich. As a reference, you can check official documentation here: http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html
It’s not very good as a starting point, but rather as a reference for more complicated cases.
To start your adventure with OData we would reccommend some of the tutorials available online.

What is JSON PATCH?

JSON Patch is a format for describing changes to a JSON document.
It can be used to avoid sending a whole document when only a part has changed.
When used in combination with the HTTP PATCH method, it allows partial updates for HTTP APIs in a standards compliant way.
The patch documents are themselves JSON documents.

This paragraph provided example of using the PATCH request with JSON PATCH syntax used in the body of such requests.
A JSON Patch document is a sequential list of operations to be applied to an object.
In this case, the body payload is a JSON array of objects: every object is composed of an op field, a path, and a value.
The op field describes the operation to perform on our target, path refers to the name of our field, and value is the replacement for our target.
The request will replace certain field with the new value. Furthermore, the op field accepts a bunch of operations on data, including:

  • Add
  • Remove
  • Replace
  • Move
1
 PATCH /Api/v2/Members/UpdateMemberDetails/12345 Host: company.perfectgym.pl Content-Type: application/json-patch+json [ { "op": "replace", "path": "PersonalData/Email", "value": "test1234@perfectgym.com" } ]

As a reference, you can check official documentation here: https://datatracker.ietf.org/doc/html/rfc6902/