API versioning
Finazon provides several interfaces for data:
-
REST API
-
gRPC API
-
Streaming via WebSockets
Let’s look into API versioning. As you can find in documentation, we support the following URLs to REST API:
-
https://api.finazon.io/latest -
https://api.finazon.io/v1 -
https://api.finazon.io/v1.0
Similar URLs we use also for gRPC:
-
grpc-latest.finazon.io:443 -
grpc-v1.finazon.io:443 -
grpc-v1-0.finazon.io:443
Let’s analyze, which is better to use, latest, v1 or v1.0?
First, I must say that the full version format as you see is vX.Y, where X
is major version and Y is minor version. We plan to change the major version
in absolutely rare cases. For example, if we will release API with new data formats or build
new API architecture. But minor changes we plan to to more often. For example, when we make
spot changes some data type in API. Or rename the request parameter or names in the response.
We plan to make releases with new minor versions not so often too, once in several months.
Of course, we update API more often, several times per week. The full API version inside of our team
has semver specification vX.Y.Z, where Z are patches and new features
that have no side effects with other features. Therefore it is enough to show in the API for
our customers only major and minor versions.
Second, we run several API versions at once. But not forever. When we release v1.1,
we run v1.1 with v1.0 parallelly. You can connect to any of them.
We announce at this moment that v1.0 has become deprecated and will be shut down
for example in a month. At the moment of release, the latest will change its point from
v1.0 to v1.1.
If you're just getting familiar with API, of course, you will take the URL with the
latest version. This will economize your time in making the first steps.
But if you build a stable application integrated with Finazon, take into account the way with
specifying full version vX.Y, for example, v1.0. When we release
a new minor version, this may break your code if you use latest. If you use a concrete
version, you will have time to test your code with the new API version and switch to new version
when all your tests are passed.
If you do not want to take care of our API version, you can use one of our official libraries. Just update it regularly and do not forget to test your code after updates.