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.
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:
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.
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.
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
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.
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:
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/