Institute for
HSR

Web API Design & Evolution (WADE)

Application Programming Interfaces (APIs) have been around for a long time, both program-internal (local) ones and remote APIs connecting processes and systems across networks. In recent years, API design and management have become an important topic acknowledged by analysts (see for instance Gartner's strategic technology trend no. 8 for 2017 (mesh app and service architecture) and vendors (see for instance this CA blog post).

 

APIs are required to realize microservices and to practice Domain-Driven Design. They often are part of a DevOps approach: an API needs to be developed and operated along with its provider implementations, but certain APIs can also be act as enablers for DevOps initiatives (e.g., APIs used for automated provisioning and distributed log analysis). Thousands of Web APIs exist today, and more are being built. The ProgrammableWeb directory lists many of them.

 

General architectural principles and patterns are eligible for API design (for related general advice, look here), but additional, API-specific ones apply as well. For remote APIs, the fallacies or distributed computing come into play (although some might say these fallacies are no longer relevant in the cloud age; see for example this opinion).

 

We cover the topic in IFS courses on the subject, for instance this one (note: the course is available in German and in English - unlike the Web page describing it).

 

POINT Principles for API Design


An API should get (and stick) to its POINTs:

  • P – an API must be purposeful (i.e., driven by the information need of its clients and their use cases/user stories). This principle is also called design-by-intent sometimes. Many APIs serve multiple clients; other are specialized for a particular one (Sam Newman calls the latter approach backends for frontends).
  • O – an API should expose domain objects in the form and concept mandated by the chosen architectural style and integration technology (e.g., resources in RESTful HTTP or WSD/SOAP Web services) and should adhere to Software Engineering (SE) and Object-Oriented (OO) principles such as high cohesion/low coupling. There should be one and only one way to execute a use case or user story to make the API lean.  
  • I – each API call should be as isolated as possible (i.e., free of unexpected, undesired side effects); statelessness helps with that, as well as specifying pre- and postconditions. This  principle corresponds to the I in an IDEAL cloud application architecture (see this presentation). 
  • N – an API should be neutral, i.e. not optimized for any particular client and/or channel (unless this is its very purpose and it is supported by neutral backend services/APIs).
  • T – an API should be T-shaped (i.e., offer broad and deep calls); it may be organized according to the master-details metaphor and/or provide search-and-iterate-through-results functionality.

 

Quality Attributes for APIs ("APIlity")

  • APIs should meet the performance and availability requirements that have been stated for them in a specific and measurable way; preferably, the rationale for their design should be made explicit to ease their consumability, but also API evolution and maintenance  (see here for some related method guidance).
  • API should be consumable for developers and their app(lication)s
  • APIs should be extensible and be able to evolve, preferably without breaking existing clients (backward compatibility)

 

Some Initial/Random Design Advice

  • Follow a recognized analysis and design method to identify API call candidates and flesh out their invocation syntax. 
  • Amend each call and/or entire endpoint with an SLA that contains one more more quantified SLOs.
  • Define an API lifecycle management policy that Balances agility and stability (see this presentation video for an example)

Five "golden rules" for Web API design are listed and discussed here: "Documentation, Stability and Consistency, Flexibility, Security, Ease of Adoption"

 

Best Practices Presentations and Articles

 

API Contract Management Notations


Vendor Offerings and Open Source Assets (Ad Hoc/Random Selection)

 

API and Service Design Patterns

  • Most pattern languages focus on design and architecture of API implementations and (SOA) infrastructure rather than the actual APIs and service message content; this one is an exception
  • Emerging: Conversation Patterns (by G. Hohpe)
  • Interface Representation Patterns (IRP) under construction (first paper accepted for EuroPLOP 2017; see this presentation for context and overview)

    • Structural patterns: Atomic Parameter List, Parameter Tree, Pagination, Id Parameter, Entity Parameter, Metadata Parameter
    • Quality patterns: SLA-SLO, API Key, Rate Limit, Request Bundle, Wish List, Error Reporting
    • Content Semantics and Granularity patterns: Master Data Service, Linked Reference Data, Embedded Reference Data, Command Service, Query Service, Validation Service
    • Evolution patterns: Version Identifier, Semantic Versioning, Two in Production, Aggressive Deprecation, Experimental Preview
    • to be continued (stay tuned!)

 

Contact for this page (and IRP): Olaf Zimmermann