From Good to Great API

The first thing we see about 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 to create an outstanding developer experience for your API. Let me tell you how!

Originally published at API-University.