• Global community
    • Language:
      • Deutsch
      • English
      • Español
      • Français
      • Português
  • 日本語コミュニティ
    Dedicated community for Japanese speakers
  • 한국 커뮤니티
    Dedicated community for Korean speakers

API Release Validation

Community Beginner ,
Aug 16, 2021 Aug 16, 2021

Copy link to clipboard

Copied

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!

Views

189

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
New Here ,
Sep 03, 2021 Sep 03, 2021

Copy link to clipboard

Copied

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

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Beginner ,
Sep 03, 2021 Sep 03, 2021

Copy link to clipboard

Copied

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?

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Employee ,
Sep 03, 2021 Sep 03, 2021

Copy link to clipboard

Copied

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. 

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Beginner ,
Sep 03, 2021 Sep 03, 2021

Copy link to clipboard

Copied

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?

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Employee ,
Sep 03, 2021 Sep 03, 2021

Copy link to clipboard

Copied

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. 

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Beginner ,
Sep 03, 2021 Sep 03, 2021

Copy link to clipboard

Copied

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

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Employee ,
Sep 03, 2021 Sep 03, 2021

Copy link to clipboard

Copied

Yep, exactly.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Beginner ,
Sep 07, 2021 Sep 07, 2021

Copy link to clipboard

Copied

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. 

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Employee ,
Sep 07, 2021 Sep 07, 2021

Copy link to clipboard

Copied

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

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Beginner ,
Sep 07, 2021 Sep 07, 2021

Copy link to clipboard

Copied

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.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Employee ,
Sep 07, 2021 Sep 07, 2021

Copy link to clipboard

Copied

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.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Beginner ,
Sep 07, 2021 Sep 07, 2021

Copy link to clipboard

Copied

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.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Employee ,
Sep 07, 2021 Sep 07, 2021

Copy link to clipboard

Copied

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

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Community Beginner ,
Sep 07, 2021 Sep 07, 2021

Copy link to clipboard

Copied

LATEST

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.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Resources