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

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.

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, which first name is John:

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

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 build also 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 oficial 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.