I would like to ask you about API versioning/breaking changes that are happening in API v1. To be honest, I don’t really understand the ‘v1’ part, as the versioned API should be fixed and updated only when critical design flaw is discovered.
This doesn’t seems to be the case with Pipedrive API, as according to wayback machine there were 6 versions of API since it was released and last change as of today (October 7, 2022) definitely contained breaking changes. (change in data types of existing field(s) etc.).
According to changelog there are two more breaking changes planned in two following months.
We want to use pipedrive API in production and we want it to be reliable enough not to cause outages and/or failures for our services, but if the https://developers.pipedrive.com/docs/api/v1/openapi.yaml endpoint is really the only one that is available and is not fixed, I don’t think we can safely count on Pipedrive to provide us reasonably stable interface for our application.
My question is - I am missing something? (which is completely possible as I just recently started to develop API client for Pipedrive) Are there e.g. any other endpoints, that would be better suitable for production usage?
Firstly, I’d like to provide some context into our current process:
We currently don’t plan to release a v2 of the API. Our strategy is to keep evolving v1 in a safe manner with enough notice (at least 60 days) of every breaking change via our Changelog.
We’ve written out what we consider breaking vs non-breaking here in our Developer Docs if you’d like to check it out. If you subscribe to our Changelog, you’ll also get emails of the upcoming changes as they are posted.
We are always eager to hear how we can improve, so I have some clarifying questions. Could you tell me:
Which endpoints/resources are you looking to use from our API? You mentioned that “there were 6 versions of API since it was released”. I’d be interested to hear which endpoints you have in mind.
What would you consider a “reasonably stable interface” in terms of versioning/breaking changes? Any examples you could share with us? Seeing as we give at least 2 months of heads up (and longer for more impactful changes), is that enough/not enough for your use-case?
You also mentioned that you recently started to develop an API client for Pipedrive. What language is it in? What’s the use case?
Feel free to DM me if you’d feel more comfortable replying privately.
Cheers,
Helena
Hi Helena, thank you for the answer!
I’ll try to answer all your questions, but I’ll not be specific, if that’s ok. I’d like to keep the discussion public for future reference.
I completely understand that the idea of continuously improving the API together with the application sounds appealing from your perspective, but it seriously worries me right now.
The main issue with this approach is that if any breaking change occurs (and you said there will be one in the future), it takes time to react. Even if I’m informed in advance, it does not improve the fact, that I need to ‘set the alarm’ for the specific date, generate new client from OpenAPI specification and possibly fix all affected projects.
That may take significant amount of time. That’s why the API versioning is so important - when there are breaking changes to implement, they are implemented to new version of API, and announced few months in advance. For some time both new and previous version runs alongside, giving the API users time to switch to new version, then the previous version can be deprecated and ultimately shut down.
The important thing in that is that providing users time to switch to new interface without any outages, properly test their integration and release their applications upgrade before the old API is removed.
So to answer your questions:
As I’m just beginning with implementation, the scope of API usage will very likely change. However the ‘6 versions’ that I mentioned were total changes in whole OpenAPI specification as registered with time machine, I didn’t really compare specific versions to each other, but the last two versions definitely contained “breaking changes” (e.g. change of data types of existing fields) in some endpoints. It does not really matter which endpoints were affected, the thing I worry about is that some of the endpoint I’ll be using will break in the future
The thing that worries me is the impossibility to avoid downtime in my application (without lots of work on our side). “Reasonably stable interface” would be one, that releases versions as I described earlier, allowing me to adapt to new changes without any downtime. Or do you have at least some “bleeding edge/beta” API that could be used for implementation and testing of new changes? It would be far from ideal, but could at least reduce the possibility of prolonged downtime (in case of unforeseeable issues during implementation
I don’t really want to be specific about languages and endpoints I use/will be using, hope it’s ok. . However there is currently no client library for my language, at it’s neither Javascript nor PHP
To summarize it - without enough time to react to changes in your API in advance, there will always be downtime in client applications. On the top of that, most of the systems’ API I used in past, had fixed APIs and after implementing the client I could forget about it. With Pipedrive, I need to subscribe to changelog and hope that I’ll not be facing any issues during the implementation and that the downtime will be reasonably short.
I’ve just created an account to add a big +1 on @ivoh 's messages. I hope this thread is going to be shared with the engineering team. The way Pipedrive handles API changes is going to impact our business since we consume the data in production. We are left without any solutions or guidelines.
We found out a bit late about the breaking change that is going to happen tomorrow to enable multi-labelling on deals/persons/organizations.
The “graceful period” is actually not a migration window where we can perform a safe double-run and transition to the new changes. It just says that the change is going to happen on 29th March. The plan to mitigate downtime was to schedule an update on our system as soon as you release the change, i.e. on the 29th of March.
But after reading carefully, there is a “gradual rollout” so we actually don’t know when it’s going to happen.
We are now excited to announce that from March 29, 2023, we will start the gradual rollout of this change.
I contacted your support and I was left with this answer:
I understand well your question but unfortunately, we’re not able to specify an exact date as these implementations depend on the needed tests and their results and how the gradual rollout evolves which can vary in results, duration, and in complexity.
More information and guidelines to manage such changes would be appreciated from Pipedrive. All the mentioned points by @ivoh would solve our issue.
Thank you for taking the time to write out your thoughts and share valid feedback!
We totally hear you and understand that a gradual rollout like this one is difficult to plan into your workflows! We apologize for the inconvenience this has caused.
I have forwarded your feedback to our engineering team, and we’ll be giving this topic some deeper thought!
I’ll join the conversation and say:
You should stop doing breaking changes to the api ASAP.
If you do not, as a business, you will lose a massive amount of customers and lose reputation.
The reasoning is simple:
The API provides a business-critical data infrastructure for a lot of applications.
There can be integrations/SDK that are done one one-time basis, without on-going support.
It is when company A, orders such an integration from company B, and after company B delivers it, the integration is supposed to work for years ahead, since APIs are not supposed to be changed. That’s how many deals in IT are done.
When APIs break, then integrations break → and that disrupts business processes of your clients, disrupts businesses of their clients and so on along the chain. Causes additional maintenance needs and unpredictable costs. The damage from breaking APIs can be enormous and that’s why companies have this term called SLA that’s being close to 99.999% as stated on many websites.
With all respect:
Stop breaking your API at once. APIs must be reliable.
Instead, release a separate API v2 and while still supporting v1 for a few years, broadcast to your clients, that v1 will be eventually deprecated and turned off and that they should eventually move to a new, a reliable v2.
Thank you for sharing your thoughts and valid feedback!
I have shared also your thoughts with our engineering team and we are taking a look at this topic! Our goal is to make your developer experience as seamless and reliable as possible, and we understand completely that the current approach can cause friction.
. However there is currently no client library for my language, at it’s neither Javascript nor PHP