API Release Validation

[default6at0d6ti5xy8]

We are considering using the Document Services API, primarily for the merge capability, and am wondering how releases of new API versions are handled?  Is there a test environment where customers can try out and test the new release before it goes live?

Thanks!

[nora.u]

Hi there - Please refer to the versioning and support information here: https://opensource.adobe.com/pdftools-sdk-docs/release/latest/policies.html#versioning Thanks!

[default6at0d6ti5xy8]

Thanks - that is helpful, although I am still not clear when it comes to the API how I control which version I am calling?  The documentation indicates there is a unique "assetId" - which I see in the request object - but how do I know what assetId to use?  Is there a unique assetId that aligns with the version numbers of the SDK?  Maybe that's in another piece of documentation?

[Raymond Camden]

The assetIds do not correspond to a version, just to a service. Right now there's no way to specify a specific version of our APIs. 

[default6at0d6ti5xy8]

So the API is not versioned?  Aren't the SDKs just a platform specific library to make it convenient to call the APIs?  If so, then it sounds like consumers take regular updates even when they don't change the version of the SDK they are using.  Is that correct?

[Raymond Camden]

They are versioned, but there's not a way for the developer to specify a version to use when hitting the end point. We've seen multiple requests related to this so it's something we know needs to be addressed. 

[default6at0d6ti5xy8]

So what is the SDK doing?  Doesn't it hit the API under the covers?  If so, is it always calling the latest version?

[Raymond Camden]

Yep, exactly.

[default6at0d6ti5xy8]

Seems like a significant risk for both Adobe and it's clients.  Also - the documentation should make this more clear.  The SDK is versioned, the API is not. 

[Raymond Camden]

We do document when breaking changes occur so folks can decide when to update their SDK. The API would *not* change in such a way as to break existing users. We cover more about this here: https://opensource.adobe.com/pdftools-sdk-docs/release/latest/policies.html

[default6at0d6ti5xy8]

Even if you don't make breaking (backward-incompatible) changes to the API, you could still release a bug.  If that happens, every single production application consuming that function would break, regardless of what version of the SDK they are using.  Consumers would be stuck with the bug until you released an emergency fix.  If every release had a new version number, you would avoid that risk.

[Raymond Camden]

I hear ya. The ability to specify a specific API version is something we are aware of, so for now the best I can tell you is that we know it's something some of our users will require.

[default6at0d6ti5xy8]

I would think Adobe would want to do it for their own sake.  Releases are a lot more high risk introducing a bug means breaking the production applications of ALL your customers.

[Raymond Camden]

As I said, we're aware - and I'm flagging it again next time we meet with engineering. Thanks for raising this.

[default6at0d6ti5xy8]

Also - I don't think consumers want the ability to explicitly chose an API version independent of SDK version - we want to know that the version we are on will never change.  SDK version and API version should be one thing.