An All-Purpose API

An All-Purpose API (AP-API) embraces all that an entity is and does. It extends the traditional API which handles domain data (books, native wildflowers, films) to include things about an entity itself, and how that entity would like others to interact with it.

In this article, we consider how we might protect an API from being cannibalised by multiple external interests (LLM agents). By adding context to our API we influence how our data are used.

An AP-API may be seen as a practical interpretation of Contract-based Web Design.

The value of All-Purpose APIs

LLMs need data to act on, and data must be secure. LLMs cannot be given unfettered access to databases or have knowledge of their internal schema.

APIs provide a controlled and safe way to access data whilst preserving an entity's privacy and honouring data protection issues.

An AP-API works on the same principles as an API.

Internal value of AP-APIs

An AP-API is the single source of truth:

  • From which the API is derived
  • From which the database scheme is derived
  • Which front and backend developers use as the contract in contract-first development whilst iterating on the API
  • Is the reference for front and backend tests

Additionally it is:

  • The source of tariffs and pricing details
  • The home for business rules and statements pertaining to ethics, sustainability and accessibility
  • A conduit for information from other systems e.g. bug tracking and source control

External value of AP-APIs

Because an AP-API adds to an API, it is attractive to LLMs which are gluttons for data.

  • Watermarks, trademarks and copyright
  • Design solutions (widgets, components, best practices)
  • Information pertaining to the quality of the data
  • Information pertaining to how the data were derived and by whom
  • Teasers, promotions, links and inducements

The AP-API is an opportunity for web development teams to articulate different modes of presentation and to take the lead on how their data should be used, explored, exploited and processed.

APIs are typically defined by a schema but endpoints and examples are probably enough for LLMs to work out what to do. Which is good news for web development teams because schemas are not trivial.

Setting up an AP-API

  • Create an API if there isn't one
  • Internal uses
    • Single source of truth in contract-first development
    • Single source of truth for front and backend tests
  • External communication
    • The interface for data exchange. Consumers may be other programmes, apps, sites or LLMs
    • First step towards an entity opening itself up to unknown interested parties

Converting an API into an AP-API

An API is-an AP-API. You don't have to change anything. But you might want to so that the world knows more about you.

It's a good way to document (in a serious, maintainable way) how the different parts of your entity work. This will help them better communicate with one another.

It can also be used to support non-technical parts of an entity such as sales and marketing.

An AP-API encourages a rethinking of how we want our data to appear in the world. It's unlikely that it will be via 'monolithic' apps or sites. This has a huge knock-on effect on job titles, team dynamics, tooling, etc.

In conjunction or in parallel with setting up an AP-API, consider How to break down monolithic apps.

AP-API example: The sales deck

A sales pitch or deck is created from an AP-API.

Given a clear brief, a combination of people and code possibly involving an LLM, creates a sales deck which the sales team can be confident represents the services they are selling.

  • The data part of the AP-API has endpoints which explicitly state what can be done (which services can be offered).
  • Employee biographies, repositories and bug tracking tools can be parsed to work out what is achievable (which promises can be met).
  • Other departments can be confident they are working in-step with sales because of the single source of truth AP-API.

Pros and cons of AP-APIs

Pros

  • Teams prepare for inevitable change (even though the nature of the change is uncertain)
  • They retain knowledge by adaptation, creating teams that are better suited to ecosystems in which LLMs are prevalent, and access to data and ideas is distributed and unpredictable.

Cons

  • Maintenance of the AP-API may be costly
  • A single source of truth paradigm excludes other approaches
  • It may be an overly mechanistic solution that blocks creative thinking and novel ideas
  • A one-size-fits-all solution may lead to loss of detail, nuance and turn everything grey

We've added more cons than pros. That's sensible. This is a sketchy, unproven idea and we are assuming LLMs will be prominent, ubiquitous and capable, unsupervised, of constructing complex solutions from disparate parts.

Conclusion

The reason for an AP-API is to prepare us for a digital future in which traditional sites and apps are replaced by LLMs that consume data from multiple sources and create custom interfaces for their clients.

Because an AP-API is-an API it is the sine qua non of contract-first development, and the interface for mediating requests from and responses to known consumers.

An AP-API is also how we shape future discourse with LLMs. In order to have some say in how our data are presented, we (entities) provide context to our data through the AP-API. This might take the form of lots of widgets, or public components that can be assembled in multiple ways. Programming Lego.

A word of caution. The value of LLMs is unclear in most cases. Do not become overly reliant on them. Treat LLMs as disposable.

This article was finished on 21st December 2024 and published shortly after.

References