Beautiful UI? What about beautiful DI?

APIs are to developers what a great interface is to an end user. Like curb appeal for a house, these APIs should be beautiful and represent the rest of what you’ve built. So why don’t we focus as much on creating beautiful Developer Interfaces (DI) as we do on User Interfaces (UI)?

Most of the points I’ll make here focus on REST APIs, but could easily extend to an Interface in Java, or a .h file in Objective-C. In all APIs, much of our time should be spent agreeing on, polishing, and simplifying our interfaces before we publish them to the end customers; in the case of REST APIs, these end customers are other developers. 

Here are the high-level bits which contribute to a great API:

• Consistency. Not everyone agrees on how a great REST should look (see pragmatic versus pure REST), but I think everyone can agree that being consistent within your own API is of paramount importance. If you’re not sure of a great direction to go, then I’d recommend leveraging good design from well known APIs, or consulting some of the great material published by the fine people of Apigee
• Great documentation. This is absolutely essential. Without clear, comprehensive, documentation, the developer will quickly become frustrated with your work, no matter how simple the API. Don’t assume anything. Get all of the API call nuance down in writing. If the developer has to come to you with questions, it’s likely the case that you’ve failed in delivering great docs, and suggests you should probably update the documentation to support them with an answer. The Django REST Framework is a fantastic example of a tool which makes REST API creation auto-documenting with a beautiful API web explorer.
• Simplicity. A great API URL should read like clean code. In reading the URL as a developer, I should easily be able to understand the general function of the call, then I’ll go to the documentation should I need additional detail.
• Flexible. Although tough to predict the future needs of your API, it’s always great to consider flexible design that might allow future client applications features to be built without a lot of additions to the API. If today, the API only requires that it return 20 items per page of a given object, perhaps you could still build in flexibility which allows the consumer to set the page size. Simple example.
• Gain Consensus. As a former colleague once exclaimed, “we should think of our APIs as a formal contract between two parties”. Thinking of it this way, we should strive to incorporate API consumers, the developers, into all conversations related to its design. This is especially important for internal APIs and more challenging for public 3rd party APIs, like Twitter’s. That said, we should make all potential consumers of the API aware of the contract details before final publishing. As contracts, APIs can be tricky to change once released, so getting early input from developers can dramatically reduce the API churn and  the need for awkward developer workarounds by consumers of your API.  

Here are some reasons for spending time on API design and documentation:

• Saves development time. Having consumer developers involved in the design and development of your API will help ensure its written for them, instead of being dumped in their laps. If you put in the effort, they’ll acknowledge the attention to detail and reward you (or, they should). A simple interface will save them time, money, and headache. They won’t need to employ hack work arounds, or approach you with questions about the intent of a particular end point. Life will be good.
• Reduced churn.  By having API consumers involved in the API design, you’ll be less likely to require change to the API. Likewise, if you spend more time designing a simple, yet flexible contract, then you’ll spend less time adding calls, parameters, and features in the future.
• Increased developer happiness. Developers love nothing more than working with great tools which make them look smart. Simple interfaces make them feel empowered and also let them get more stuff done; these are good things that can only help the platform you’re building for them. 

At the end of the day, the API is the only thing a developer (your API’s customer) will see of your work. They won’t likely have access to the details behind, and really don’t want to be in the business of caring how it was implemented. They want to have something that’s easy to understand and feels like a powerful tool instead of something they fight against. They want to be inspired to build incredible features, quickly. Regardless of whether you’re writing this API for internal company use, or 3rd party developers, we should all be shooting for accessible, easy to leverage, consistent and beautiful APIs. Just as we care deeply for creating beautiful user interface experiences, we should also be striving for incredible developer interface experiences. 

Save a Developer today, start, or continue, caring about creating exceptional DI (Developer Interface), just as we do UI (User Interface).