The LinkedIn Way of Building API Versions

Write for InfoQ

LinkedIn recently revealed how they built a new versioned API framework for LinkedIn Marketing APIs that allows external partners to migrate to newer versions of APIs at their own pace.

With the new framework, each API product exposes its versioned models and APIs through a mid-tier that serves APIs for external partners. The mid-tier APIs and models are exposed to the external world with specific versions. This allows their consumers to migrate to the new versions at their pace.

Legacy architecture consisted of backend APIs built by various business lines and exposed externally via Rest.li API gateway. Since these APIs were not versioned, everything implemented for the internal APIs was published to the external customers directly.

The post explains: "Unversioned APIs also blocked customers from accessing the latest features and caused internal challenges with new feature development. Additionally, feedback from developers indicated we were releasing too many API changes with short warning times that disrupted planning."

Source - https://engineering.linkedin.com/blog/2022/-under-the-hood--how-we-built-api-versioning-for-linkedin-market

LinkedIn built the new framework to expose changes to models and APIs under specific versions to effectively isolate external applications from changes and allow partners to migrate to new versions at their own pace.

Whenever an external application requests a specific API version, the API gateway translates the request and forwards it to the appropriate mid-tier.

Like any other API gateway, the API gateway in this architecture brings authentication, request Mapping, throttling control, authorization, anti-abuse control, and request dispatching.

Ultimately, the mid-tier exposes the features implemented by backends to the external applications.

There is only one mid-tier per API product.

Source - https://engineering.linkedin.com/blog/2022/-under-the-hood--how-we-built-api-versioning-for-linkedin-market

Different versions of the same logical resource can co-exist within the mid-tier, and this reference is maintained in the code. The gateway calls desired resource version using the request mapping.

The services in the mid-tier are responsible for calling the backend version agnostic services from the business lines. If services maintain this version-specific logic in code, it may cause code-maintenance problems. To avoid this, the team built the "Versioning Execution Framework" library that accomplishes the following two essential things: converting the request to the latest possible version via user-defined transformation, and once the request is converted into the latest possible version, it is then converted to the latest available internal model again via the user-defined internal model converter.

The implementation highlights LinkedIn’s design principle of "don’t disrupt customers."

With LinkedIn's Marketing APIs versioned since June 2022, developers and partners can use these stable APIs.

Related Topics:

• Development
• Architecture & Design
• API-Design
• Microservices
• API
• API Gateway

We protect your privacy.