The first thing we see as users of a new web application is typically its user interface. This is why user-interface design is so important for web applications. Now, user interface design is for web applications, what API frontend design is for APIs. The results of the frontend design are directly visible to the consumer of the API, who develops apps using the APIs. This is why the frontend design is said to have an effect on the developer experience (DX), in analogy to the user experience (UX) of user interfaces. In the eyes of developers, great API frontend design can turn good APIs into great APIs.

API frontend design depends on the architectural design decisions made earlier: API frontend design is different for RPC, SOAP, and REST APIs. REST APIs are the most common form of APIs built today. In the API Design book, we focus exclusively on the design of REST APIs.

API frontend design lends itself to contract-first design. What does the contract specify? The API frontend design contract contains a specification of the endpoints, URLs, parameters, methods, the data models, data formats etc. Such a contract can be captured using API description languages such as Swagger or RAML.

So do proper RESTful design and use API description languages, such as OpenAPI to create an outstanding developer experience for your API.

From Good to Great API

Also published on Medium.

Matthias Biehl

As API strategist, Matthias helps clients discover their opportunities for innovation with APIs & ecosystems and turn them into actionable digital strategies. Based on his experience in leading large-scale API initiatives in both business and technology roles, he shares best practices and provides both strategic and practical guidance. He has stayed a techie at heart and at some point, got a Ph.D. Matthias publishes a blog at api-university.com, is the author of several books on APIs, and regularly speaks at technology conferences.