Skip to content

Architecture Decision Record: API specification

Context

DPL CMS provides HTTP end points which are consumed by the React components. We want to document these in an established structured format.

Documenting endpoints in a established structured format allows us to use tools to generate client code for these end points. This makes consumption easier and is a practice which is already used with other services in the React components.

Currently these end points expose business logic tied to configuration in the CMS. There might be a future where we also need to expose editorial content through APIs.

Decision

We use the RESTful Web Services Drupal module to expose an API from DPL CMS and document the API using the OpenAPI 2.0/Swagger 2.0 specification as supported by the OpenAPI and OpenAPI REST Drupal modules.

This is a technically manageable, standards compliant and performant solution which supports our initial use cases and can be expanded to support future needs.

Alternatives considered

There are two other approaches to working with APIs and specifications for Drupal:

  • JSON:API: Drupals JSON:API module provides many features over the REST module when it comes to exposing editorial content (or Drupal entities in general). However it does not work well with other types of functionality which is what we need for our initial use cases.
  • GraphQL: GraphQL is an approach which does not work well with Drupals HTTP based caching layer. This is important for endpoints which are called many times for each client. Also from version 4.x and beyond the GraphQL Drupal module provides no easy way for us to expose editorial content at a later point in time.

Consequences