API Versioning

[kirrg001]

Why API Versioning?

• We want to avoid that external clients break if they update their Ghost version. You either need to update the client first or your blog. You will always break clients for a period of time. With API versioning there’s no pressure to update immediately. You can even update to a new major version of Ghost without breaking your clients.
• The public API is in beta since years now and we would like to work on a stable public API version.
• The public and private API live on the same url (/api/v0.1/), but they both have different characteristics e.g. authentication, response values, restrictions. Having both on the same url makes it harder to maintain the code.
• We would like to overhaul our current authentication strategies. Covered by API v2 - Authentication #9865.

Future of Ghost

In the near future we would like to achieve a 3 way split to make Ghost more customisable and flexible.

These are: Ghost Core, SDK’s and Clients.

Ghost Core

Should become API centric in the future, future. That means, our suite of APIs will be first class citizens allowing Ghost to function as a headless CMS.

SDK

Our suite of tools intended to help developers make use of APIs in their clients. SDKs should offer commonly used functionality that works on top of the data provided by an API in the form of small, reusable modules or components.

Clients

The ultimate API consumers. Some are interacted with by users, some by computers. They share common needs and so should be as small as possible, relying on shared code from the SDKs to solve common problems.

Reference Material / Research

• Facebook
  • https://developers.facebook.com/docs/graph-api/changelog/breaking-changes
  • They use e.g. v3.1 versioning notation.
  • Reason for that is that want to lists the features they have added in the current major version. At Ghost we can update our docs based on the current minor Ghost version.
• GitHub
  • https://developer.github.com/v3/versions/
  • They use major versions only e.g. v1, v2
  • They use headers to transmit the version e.g. Accept: application/vnd.github.v3+json
• Stripe
  • https://stripe.com/blog/api-versioning
  • https://stripe.com/docs/api#versioning
  • They use a mixture.
  • Dated versioning - the date when the API version was released.
    • in a Stripe-Version header
  • /v1/ as standard API endpoint
• Contentful
  • https://www.contentful.com/developers/docs/references/content-management-api/#/introduction/api-versioning
  • They use major versions only e.g. v1, v2.
  • Content-Type: application/vnd.contentful.management.v1+json
• Restify
  • http://restify.com/docs/home/
  • Uses Accept-Version: *
• General API change management guide and very interesting reads:
  • https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/
  • https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown
  • https://www.mnot.net/blog/2012/12/04/api-evolution
  • https://apigility.org/documentation/api-primer/versioning
  • https://blog.goodapi.co/api-maturity-fb25560151a3
  • http://www.ben-morris.com/rest-apis-dont-need-a-versioning-strategy-they-need-a-change-strategy/
  • http://apiux.com/2013/05/14/api-versioning/
  • https://projects.tmforum.org/wiki/display/API/Entity+Versioning+and+Lifecycle+Management
  • https://cloudplatform.googleblog.com/2018/03/API-design-which-version-of-versioning-is-right-for-you.html
  • https://yalantis.com/blog/api-versioning-with-ruby-on-rails/
  • Add support for header-based versioning dotnet/aspnet-api-versioning#70

Main Goals

• Rename Public API to Content API and Private API to Admin API
• API versioning for the Content and Admin API
• First stable Content API
• Admin API goes into Beta
• Do not break v0.1 API
• Support three API version at a time

API Versions

Based on the research material, we have decided to go with major versions only.
Examples for major versions: v1, v2, v3, v4 etc.

Reasons why we go with major versions:

• Research material showed us that this is a very common approach.
• We don’t want to force our clients to update their API version with any new feature/addition.

The Ghost active API version should equal the current major Ghost release. The latest Ghost major version is Ghost 2.x, that means we will introduce API version v2.

The latest/active API version should add concentrate on adding forwards compatible changes (add features, add routes, add new fields). As soon as we have to introduce breaking changes we have to:

• add a new unstable (alpha/beta) API version
• ensure we don’t break the old API versions

How does future versioning work?

The basic concept is (3 versions at a time):

• current active version (feature additions)
• stable version
• deprecated version

Examples:

Ghost 2.0

• v0.1
  • stable
• v2
  • active version
  • breaking changes allowed initially, from there on only new functionality and forwards compatible
• v3
  • we start with v3 as soon as we have breaking changes
  • we will release v3 before shipping Ghost 3.0
  • v3 becomes alpha/beta in Ghost 2.0
  • v3 becomes active in Ghost 3.0

Ghost 3.0

• v0.1
  • deprecated, won’t break
• v2
  • stable, won’t break
• v3
  • active
  • new stuff allowed
  • breaking changes are not allowed
• v4
  • we start with v4 as soon as have to introduce breaking changes, same as above

Endpoint design

Two new endpoints for v2 will be introduced:
We have decided to use url versioning, because it fits better to Ghost needs.

Reasons against API headers:

• you can't put a header when accessing the url in the browser
• it's harder to cache public/content api requests when using a header
• if you don't provide an api header, you would fallback to the latest api version, which can create an unintended behaviour for clients
• it's harder to add a header than putting the version into a url
• we want to be explicit

The actual design

• /api/v2/content/
  • public, read-only
  • v2 becomes active version
• /api/v2/admin/
  • private, CRUD
  • goes into beta
• /api/v0.1/
  • currently in beta
  • becomes “stable”
  • won’t break

Themes are clients

The theme has access to the API layer. It get’s data in and can pull more data from the API using the {{get}} helper. The theme layer is coupled with the actual blog site. They are both one client using the API. All themes currently use the API version v0.1.

We will introduce a new theme configuration option to define which API version you would like to use. This configuration value will probably live in the package.json of a theme. For now, if no api version is configured, we fallback to v0.1.

In the future it might be possible to define the version per helper, but that would be a future improvement.

Code Challenges

The biggest challenges are:

• come up with a future proof folder structure to support api versioning
• decouple model and api layer
• decide which is shared functionality and which is not
• granular API layers per API versions including serialisers
• make it possible to reduce the maintenance cost for writing tests per API version

[kirrg001]

Closing. The work is done here. We've raised some more cleanup/optimisation issues for API V2.
See issue references above 👍