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 GRPC clients. Just update it regularly and do not forget to test your code after updates.

Finazon • Marketplace for the Global Financial Data APIs
Finazon is a financial data marketplace covering stocks, forex, cryptocurrencies and beyond. Access real-time, historical and alternative data via API & WebSocket.
Url:
credit card
Finazon LLC