API Categorization

APIs are an integral part of our distributed system here at Pluralsight. We use them to communicate between and within bounded contexts. One of our engineering team mottoes is “Be Explicit.” To that end, we have a categorization system for the APIs we build and publish. This helps us know what the API is for and who should (and who shouldn’t) be using it.

We have two orthogonal categories for APIs. We have APIs that fit into (nearly-)all of the possible combinations of these sets of categories.

Visibility

The first thing we need to decide about an API is whether is can be accessed from outside of our data center.

Internal

These APIs can only be accessed from servers within our data center. We still follow best practices like load balancing etc, but we don’t provide any public routes to these APIs.

Public

APIs in this category have public routes and can be accessed from anywhere.

Consumer

The second question that must be answered is who will be using the API. This decision will affect many other decisions about the characteristics of the API.

Context

This API is only used within a Bounded Context. This API doesn’t have to be explicitly versioned as a Bounded Context is managed by a single team and can be released as a unit when necessary. This API will likely change quickly as the consumer(s) within the Bounded Context evolve.

System

This API is shared between Bounded Contexts. When one Bounded Context needs to synchronously query another, a System API is the answer. In the Pluralsight system, this API will be a RESTful JSON service so it can be easily consumed by the many technology stacks we use.

Versioning of this type of API must be coordinated between the team supporting the Bounded Context that exposes it and the teams supporting the Bounded Contexts that consume it. We only support three versions of any Internal API: vPrevious, vCurrent, vNext (which is currently in development). This allows the teams publishing System APIs to evolve their part of the product without the weight of legacy APIs killing their progress. If your team is consuming a vPrevious API, you should prioritize migrating to vCurrent.

Customer

This API is either intended for or is shared with customers outside of Pluralsight.

Versioning is essential as there is no guarantee that consumers will adopt new APIs as they are released. This type of API will typically be versioned more slowly than the other two as more notification is required to allow public consumers to adapt to new API contracts. We should not support more than three versions of any Customer API: vPrevious, vCurrent, vNext (which is currently in development) though the Product Managers for these APIs may make exceptions if the benefit to customers outweighs the maintenance cost to the product development team.