The Principles of API Design

This is my resumé of John Higginbotham’s book “Principles of Web API Design”

Previously API’s were built on an one on one occasion. Now the need for integration and API’s has exploded. We need a process for cost effective API design.

A Great API revolves around 3 elements

The book suggests that 3 main things must be taken into account during web API design.

      • Business Capabilities

      • Product Thinking

      • Developer experience

    An API is a conversation on 3 different levels

    Web API’s are also about conversation on 3 different levels

        • System to system communication across network boundaries (http, technical level)

        • Developer to developer. An API is a user interface for the consuming developers.

        • Business to Business or communication to the market place. What digital capabilities are we offering and what are the possible outcomes of using those capabilities.

      An API Contract is neither a Data Model or a Domain Model

      In a Resource based web API a resource represents a business concept or entity. But we should not think that a resource model is the same as a data model. Also a resource model is not a domain model. A Domain model should be changeable as well as a data model. Where as we want the api to be more stable.

       

      An API though stable must accommodate new requirements. Design for evolution and take versioning into account from the start on.

      Typical software design principles are mentioned, like low coupling and high cohesion as well as modularization. A System is synthesized of modules consisting of other modules.

       

      Object Oriented Design is Message Oriented Design

      An API model should be more like modelling messages between two persons/parties having a conversation. Take care not to leak intricate details of a data model or domain model.

      Also a note is given on Alan kays original vision of object oriented programming. Where the prime thing is messaging between objects not the functions or properties of objects.

      5 API Principles

      5 API design Principles are introduced as well.

          • Principle 1: APIs should never be designed in isolation. Collaborative API design is essential for a great API.

          • Principle 2: API design starts with an outcome-based focus. A focus on the outcome ensures the API delivers value to everyone.

          • Principle 3: Select the API design elements that match the need. Trying to find the perfect API style is a fruitless endeavor. Instead, seek to understand and apply the API elements appropriate for the need, whether that is REST, GraphQL, gRPC, or an emerging style just entering the industry.

          • Principle 4: API documentation is the most important user interface for developers. Therefore, API documentation should be first class and not left as a last-minute task.


          • Principle 5: APIs are forever, so plan accordingly. Thoughtful API design combined with an evolutionary design approach makes APIs resilient to change.

        Summary

        In chapter 1 we get introduced to concepts in 3 groups which can be illustrated like this:

         

         

        concepts form chapter 1