Clear statement regarding APIs please

Currently, large parts of the API 1.1 documents have the following banner

v1 APIs will be deprecated within the next year. We recommend switching to the v2 APIs.

But has that message been there a week or 51 weeks?

In the API 2.0 docs the following is stated

CircleCI API v1.1 and portions of API v2 are supported and generally available. CircleCI expects to eventually End-Of-Life (EOL) API v1.1 in favor of API v2 as more API v2 endpoints are announced as stable. Further guidance on when CircleCI API v1.1 will be discontinued will be communicated at a future date.

This does not really match the fixed deadline given in the v1.1 docs.

At the same time the API 2.0 docs contain statements such as

API v2 is currently in active development, therefore, the stability of the API is referred to as “mixed”.

Portions of the CircleCI API v2 remain under “Preview”

But the breaking changes log has not been updated since the end of 2019.

The overall result is public documents that express the API layers poorly and indicate that their current use would best be described as ‘building on sand’ as V1.1 APIs are to be pulled within the next 364 days, while V2.0 APIs are still work in progress.

This may sound rather negative, as I’m working at a startup the IT choices we make are often challenged by current and possible investors and our workflows are going to depend a lot on the API’s ability to trigger workflows. So this post is designed to show that I am fully aware of an area of the product that is ‘work in process’ as and when the subject gets raised again while also hopefully causing the issues to be addressed over time.

A post regarding the triggering of workflows will follow with more detail.