SolarFarmer API Versions
We currently support two concurrent versions of the API to help give you a bit of time to accommodate any new changes when we make new releases.
How it works
https://solarfarmer.dnv.com/vX/api/
- A new version (integer value, incremented with each release) of the API will be available with each
new release, and be available by the
vX/api
URL, where 'X' is the version number (e.g.,v2/api
). - The previous version will still be available via its versioned URL.
- Any other previous releases (via their versioned URLs) will not be supported and return the 410 (Gone) http status code if you try and call the API with these versions.
- We will continue with our (approximate) 3-monthly release cycle.
- Using a versioned URL is preferred
- Pros:
- It will be a consistent experience for you, with no interruption to service when there is a new release. When there is a new release, you will have 3 months to start using the newly released version.
- You are in control of when you start using a new version, rather than it being forced on you.
- Cons:
- It means updating your scripts each time there is a new release (before the version you are using is deprecated), which could be a high-maintenance task for you.
https://solarfarmer.dnv.com/latest/api/
- This API URL will ALWAYS point to the latest version.
- This is the URL to use if you're happy to be always using the latest version.
- Using this URL means that you understand that it will contain the latest version and that the calculation code called with this URL will change with each release.
- Pros:
- You don't have to change your URLs in your scripts each time there is a release.
- You're always using the very latest release, with all the latest features and bug fixes.
- Cons:
- It may break your scripts if there are any breaking changes with a new release.
- If there are breaking changes with a release, you can quickly use the previous version (using the versioned URL) whilst you update your scripts/code.
https://solarfarmer.dnv.com/api/
- This legacy API URL will also continue to point to the latest version for the time being, but will
eventually be deprecated as we prefer users to use the explicit
latest/api
URL, or a specific version of the API, so there is a conscious decision being made about which version is being used. - Please discontinue using this URL and use one of the versioned URLs or
latest/api
instead.
We are discussing the possibility of a long-term-support version of the API, which will last for longer than the 6 months of a normal versioned release. Let us know (email solarfarmer@dnv.com) if you would be interested in this.
Illustration of the versioned releases over two releases
Latest release (7 September 2023) - available API versions
v2 was released.
Version | API URL | API build number | Release date |
---|---|---|---|
v1 | https://solarfarmer.dnv.com/v1/api/ | 0.2.254 | 11 April 2023 |
v2 | https://solarfarmer.dnv.com/v2/api/ | 2.0.2 | 7 September 2023 |
v2 | https://solarfarmer.dnv.com/latest/api/ | 2.0.2 | 7 September 2023 |
v2 | https://solarfarmer.dnv.com/api/ | 2.0.2 | 7 September 2023 |
Proposed next release (approx December 2023) - available API versions
v3 will be released. v1 will be removed.
Version | API URL | API build number | Release date |
---|---|---|---|
v2 | https://solarfarmer.dnv.com/v2/api/ | 2.0.2 | 7 September 2023 |
v3 | https://solarfarmer.dnv.com/v3/api/ | 3.0.0 | December 2023 |
v3 | https://solarfarmer.dnv.com/latest/api/ | 3.0.0 | December 2023 |
v3 | https://solarfarmer.dnv.com/api/ | 3.0.0 | December 2023 |
SolarFarmer API Website
The website to get your API token (https://solarfarmer.dnv.com) is the same. There isn't a different website for each version. You use the same API token for the different versions.
The Docs tab of the website (https://solarfarmer.dnv.com/docs), where you can try out the different endpoints and see the Swagger documentation for the classes used with the endpoints, has a drop-down to choose the appropriate version number.