Migrate REST API clients from v4 to v5

Owned by Manuel Gierlinger
Jan 17, 2024
2 min read

The changes between REST API v4 and v5 may require some smaller adjustments of the client implementations, but are in general not requiring big-effort changes. This migration guide should give an overview on how to migrate from API v4 to API v5. Please note that at the time of writing this guide the API v6 was already announced and released, but the changes from v4 or even v5 to v6 are of bigger nature. 

REST API /v3 and /v4 DEPRECATION: The 23.76 (published March 2024) will be the last LTS version that includes these API versions. By early June 2024, the REST API routes to v3/v4 will be deactivated on DEMO. Early December 2024, the REST API routes to v3/v4 will be removed from feature stream releases. Note that there is no date communicated yet to discontinue REST APIv5 (and where v5 refers to v4 routes, these will still remain); however we recommend to use the /v6 API specification already.

Conceptual Changes

Instead of having all routes strictly with /v4 in the path component, the v5 is redefining on a /v5 path only those methods where breaking changes between the API v4 and API v5 make it necessary to provide different implementations one beside the other. Therefore, the v5 API contains different versions in different methods, e.g. the GET /v4/authorization and the POST /v5/envelope/send.

With API v4 and v5, the /envelope methods have been split up in those dealing with envelopes (/envelope), and those just creating/reading/updating a draft (/draft).

Changes on Method Level

Removed and Deprecated Methods

The method GET /v5/user/{email} should be considered as DEPRECATED, and GET /v5/userByEmail/{email} should be used instead, as a GET on a user, with an "email" as path variable, violates the OAS3 specification because the "userId" is the primary identifier e.g. for the DELETE or PATCH verb.

Changed Methods

The method POST /v4/envelope/create was renamed to POST /v5/draft/create.

The method POST /v4/envelope/createFromTemplate was renamed to POST /v5/draft/createFromTemplate.

While GET /v5/envelope/{envelopeId} remains with the purpose of reading details of an envelope (after it was sent), on an envelope in draft state the new method GET /v5/draft/{draftId} should be used instead of GET /v4/envelope/{envelopeId}.

Added Methods

Methods to search for users have been introduced, which allow searching for users by both types of parameters and help to provide more easily an OAS3 compliant facade in case this is required.

The newly introduced methods therefore are:

  • GET /v5/userById/{userId}
  • GET /v5/userByEmail/{email}

In conjunction with the changed methods for draft management, following new methods have been added to provide new functionality on drafts via the API:

  • POST /v5/draft/send/{draftId}
  • PATCH /v5/draft/update/{draftId}

For sending envelopes with automatic remote signature/sealing, it is required to provide the sealing profile Id in the POST /envelope/send. To allow convenient selection of sealing profiles, the following method was implemented:

  • GET /v5/organization/sealing

To allow OAuth2 use cases, following method was added (mainly for the purpose of offering data via a resource URI, e.g. to "authenticate via eSignAnyWhere"; somehow equivalent (but not fulfilling all requirements of) the /userinfo endpoint of OIDC)

  • GET /v5/user/me

Changes in the Models

Currently no detailed comparison available on this level, as there are just slight changes inside the JSON definitions.