Cachet: Drop versioning from API endpoints?

[jbrooksuk]

What are people's thoughts on dropping the versioning (/v1) chunk from the API endpoint?

Here's why I don't like it:

• It suggests that Cachet will support multiple versions of the endpoints in one installation - this is not true.
• It adds needless length to the endpoints, even though it's only three characters it adds up!
• I'm feeling restricted in what changes we can make to the endpoints before we end up having to move it into v2 (and thus drop all existing endpoints).
• The next version of Cachet will be v3 and not v2.4 so we’re free to make backwards breaking changes where needed.

Let me know what you think.

[lucasdcrk]

I also think you should drop the versioning

[nstapelbroek]

I'm at this point of life where I believe that API versioning is part of the content negotiation headers already present in the many HTTP requests we send with our browsers on a day-to-day basis. Of course this complicates it for new users since you cant simply copy & paste specific requests.

Do you perhaps have insights in stuff like:

• the biggest consumers of the Cachet API's?
• the kind of changes the API already had or stuff that you would like to change?
• considerations around GraphQL? GraphQL could handle versioning by just adding new fields and marking the old ones as deprecated if I understood correctly :see_no_evil:

edit: added the word "headers"

[ruiztulio]

It could be useful if there are plans to support more versions (keep old versions until all libraries and external tools are migrated to the new one), if not there is no case to keep it there as @jbrooksuk says.

In the other hand it is usefull to know the version to check if it changed, in my case a have a few scripts that use the api so if something change I'd like to be able to know (like querying the versin), perhaps using one like the /ping (or the ping itself)

[jbrooksuk]

@nstapelbroek Unfortunately, we don't have many stats at all.

• No idea, but very likely something listed listed at https://docs.cachethq.io/docs/client-libraries
• I'd like to look at changing some of they key/value pairs that are returned. Primarily, the way they're named or how they return data. When we finally update Laravel, I'd also like to use the Resource class.
• I've looked at GraphQL in other projects and quite enjoyed it. I also believe that Cachet would suit the GraphQL structure so this would be something we should look at. I'd be happy to leave the RESTful API alone for now, then transition to GraphQL only in v4.

[jbrooksuk]

@ruiztulio the /ping endpoint only tells you which version of Cachet is being used, so this probably doesn't help matters.

We should really have CachetHQ/SDK complete and then people could base other libraries off that as source, that way if packages/libraries are using the core SDK's for their language, it doesn't matter as much.

[awjudd]

Baking logic in based on the "/ping" version is sketchy. At least if a site has a tool that is pointing to v1 it will start failing with a 404 if that endpoint is dropped instead of a potentially mysterious error because we don't provide everything that the new endpoint needs scares me a lot.

[ygini]

Just seeing this.

From a developer point of view, this have no sense…

You're breaking third part software compatibility for no reasons and no improvement. This should be avoided.

To answer you point by point:

It suggests that Cachet will support multiple versions of the endpoints in one installation - this is not true.

No, it suggest that Cachet has been correctly designed, in a way that if someday you need to produce a non backward compatible API, you will be able to do it aside of the legacy one, letting third part developer the time to update.

It adds needless length to the endpoints, even though it's only three characters it adds up!

Meaning less consideration.

I'm feeling restricted in what changes we can make to the endpoints before we end up having to move it into v2 (and thus drop all existing endpoints).

There is no such things as feeling here… Updating the API version is as simple as non backward compatible feature update.

As long as you extend your API to add features without removing former behavior, their is no need to update the version number.

As soon as an API call isn't supported anymore, you must update the API version.

And somewhere in the header of the request you should add a customer attribut to warn the client if a request is done on a legacy API. The description of the error should contain the planned deprecation date.

This will help third part developer to do "preemptive error handling" by letting them the opportunity to automatically warn the user that their current version of the software will soon stop working.

The next version of Cachet will be v3 and not v2.4 so we’re free to make backwards breaking changes where needed.

Not if you think about ecosystem. Changing the branding of your app does not imply to break all other developer work if not needed.

You're never free to break backward compatibility when you expect third part to work with your API. You must always consider if it worth it or not.

Do you need to recreate from scratch the API in v3? Do it in /v2 and pass the /v1 in legacy until X releases

You don't need to recreate from scratch the API in v3? So don't touch it.

[jbrooksuk]

Thanks for the insight @ygini :)

[nalysius]

It suggests that Cachet will support multiple versions of the endpoints in one installation - this is not true.

Today you have no plan about multiple versions of the endpoints, but what will you think on tomorrow, or even in five years? I think it is important to be flexible, and future-proof.
Ok it's not in the plans, but this /v1 is not a problem, and it would allow us if needed one day to add a new version. The _future-proofness_ is really important to me as a developer, I don't like to be blocked one day if I can't do what I have to do because my previous choice was not flexible enough.

It adds needless length to the endpoints, even though it's only three characters it adds up!

Is this a problem? Two characters in the URL, two octets in the request is not so bad, it's even not important I think.

I'm feeling restricted in what changes we can make to the endpoints before we end up having to move it into v2 (and thus drop all existing endpoints).

For API as for the application, we should follow (more or less) semver. That's why Cachet will become 3.0 and not 2.4. An API versioning is as important as an application one.
Many libraries exist, right? If I am a library user I need to know what version of the library to use. Imagine we have no API versioning, I use a library so communicate with my Cachet instance. One day there is a breaking change in the API, but I don't know it so my software that interacts with Cachet no longer works. As a company, I could not accept it. A company needs reliable softwares or libraries, so it needs to be sure the API will not be broken. That's the goal of the API versioning.

The next version of Cachet will be v3 and not v2.4 so we’re free to make backwards breaking changes where needed.

I may be wrong, but I think the API may be backward-broken if the Cachet major version number changes. API may be broken between 2.3.14 and 3.0 or example.
At the same time I think it could slow down companies in the Cachet upgrade. A company could keep using 2.3.14 for ten years if it has a software is using it. But if the API versioning is right the company can upgrade to Cachet 3.0 because they want to use SSO or any other possible feature and keep using the API.

I am working at a company. We plan to monitor our applications, our websites, servers, databases and so on. We'd like to post the datas into Cachet in order to have a status page connected to our tools.
If we can't be confident with the API changes, I'm almost sure my boss won't want to use it. If we update our Cachet instance and all our monitoring application are broken it is a real problem.
But if a good versioning is done for the API, we could use it with confidence.

About GraphQL, I've never used it but I've read the documentation and some example and it seems to be great! I could help for versioning too.

In short:
According to me we should keep the API endpoint versioning. It is not a
problem, it already exists and it might be useful in the future.

[jbrooksuk]

Okay, the people have spoken.