Web API versions

Why do we need multiple versions?

While developing our product we always make changes in Web API. As soon as our API is used by third parties we understand, that changing API methods brings them risks of getting errors. As a result we always try to leave our public API back compatible. But sometimes we have to make major changes in order to increase system's security or changing some base features.
In order to keep our and third party's systems safe, a versioning system is involved: the system requesting API can choose whether to get old or new behavior.

What is version?

A version is a group of numbers which determines API behavior.
Dashly follows semantic versioning scheme.
Full version example: 2.10.5.

As minor and patch versions are back compatible we describe only major version changes in our public API.

When you perform an API request, you can set only version prefix in order to use the latest subversion.
Imagine, API has versions 1.0.0, 1.1.0, 2.0.0, 2.0.1, 2.1.0, 2.1.1.
If you set version 2 then full version will be 2.1.1.
If you set 1, you will use 1.1.0.

Using a version in request

You can set version in two ways:

• With URL prefix (have a look at v1 and v2 at the URL path)
  • GET https://api.dashly.app/v1/users/123
  • POST https://api.dashly.app/v2/users/props
• With GET or POST parameter version
  • GET https://api.dashly.app/users/123?version=2

Important! If you skip settings version, API uses current active API version.

Current API version and change log

Current active API version (used by default): 2

Version 3 (v3, future)

Introduces JWT-token auth. All API method, generating authentication tokens now return a dictionary containing access_token and refresh_token fields instead of string tokens.

Version 2 (v2, current)

Changed pagination scheme.

Version 1 (v1, deprecated)

Initial API version.