Introducing API 4.0.0

A walkthrough of the latest updates to DADI API featured in release 4.0.0

Today, I’m very excited to tell you all about a major update to DADI API, the brain of the DADI suite of web services. Whether you’re new to the platform and curious to see what it’s all about, or you’re already part of the family and want to know what’s new, here’s API 4.0.

A tale of two auths

Since its first version, API implements an authentication system based on the client credentialsflow of oAuth 2: a set of client credentials is exchanged for a bearer token, which gives access to protected resources that would otherwise be inaccessible. This ensures that collections and endpoints can’t be read and modified by the public (unless that’s what is intended).

However, authentication is simply about determining whether someone has the key to open the gate, but real applications are more complex than that, requiring a set of rules to determine what exactly someone can do once they’re in (authorisation). For example, in a system that represents a publishing company, it makes sense that the receptionist, a journalist and the editor-in-chief all have access to the same system, but it’s expected that the set of operations that each is allowed to perform is radically different.

Traditionally, DADI API was mostly used in a machine-to-machine configuration, whereby another application, like DADI Web or DADI Publish, talks with API on behalf of the user, rather than exposing API for a direct communication with end users. This meant that a single API client, whose credentials are secured within the context of a server-side application, can have unrestricted access to the entire dataset and be used to handle all CRUD operations on behalf of every end user.

Closer to the people

The power of an API-first stack is the extreme flexibility it allows, and whilst a machine-to-machine implementation is currently powering some pretty powerful applications, we don’t want to prescribe that configuration to anyone or to assume that’s how the majority of users will use the product.

In a setup with one or multiple native apps, and with client-side web applications becoming ubiquitous, it’s sometimes useful to establish a direct connection between the end user and the API without relying on a middleman. However, this route requires from API a more powerful authorisation layer that allows administrators to define, with high precision, what each client can and cannot access.

API 4.0 ships with a full-featured access control list (ACL), capable of representing even the most complex hierarchical structures of an organisation with the concept of resources, clientsand roles. The new version makes it possible to limit access to resources (such as collections and endpoints) to specific clients or roles, on specific CRUD operations, and with support for advanced permissions that go all the way down to field-level.

This is one of the many steps we’re taking to make DADI API a powerful, high-level application that is closer to the end user. We have some more exciting features on this front that we’ll roll out (and write about) in upcoming releases.

By the numbers

The scope and complexity of the work involved in this release was quite impressive. Here are some numbers to help you understand why.

  • The release involved 120 commits and over 18,000 lines of code over the course of almost two months (see main pull request)
  • The codebase is backed by 840 automated tests covering 89% of the code
  • All the new internal endpoints are fully described using the standards introduced by the OpenAPI Initiative and fully documented in our documentation site
  • Several spec documents, both internal and public, were released and heavily discussed amongst our core engineering team, focused on achieving the best list of requirements without compromising quality and performance — for example, despite the added complexity of validating resources of clients and roles on each request, the time to first byte has not been increased (it was actually reduced in some cases)

Getting started

To take API 4.0 for a spin, simply update the version of your dependency if you have an existing installation (make sure to check the migration guide) or fire up DADI CLI to install a fresh one. The documentation pages should give you all the information you need, but I’m always around if you have any questions.

Happy builds!


Written by Eduardo Bouças, Principal Engineer at DADI. Eduardo leads the development of several DADI dApps, including DADI API.