10 steps to design and build the perfect API

When you’re designing an API, you don’t just want to build an API. You want to design and build an API with a long life that your users will love. An API that is carefully created to be extendable and flexible, and will save your users time, money and energy in the long run. To design and build the perfect API, you’ll need to follow some best practices. While some of these may seem a little painful or like they just create more work, you’ll find that by adhering to these guidelines you will not only create a better API, but save a lot of time and money.

1. The first thing you’re going to want to do is choose an API type.  To design an API well, you need to understand why that type of API is best for your application, and then design it to work effectively.
2. The next step is planning out your API’s capabilities. Surprisingly, while being one of the most crucial steps in API development, this step is usually rushed through by companies excited to generate a product map and start working on code. You need to consider who the API will be used by, to what actions do they need access, and then you must list out those actions. You need to explain how the API will interact with existing services, how the API will be maintained, how the API will be versioned, how it will be documented, how developers will interact with it, and how you are planning to manage support. There is a lot to consider in this stage, but careful thought now will save you time and effort later.
3. Next you create a blueprint or spec for your API. Using a process called Spec-Driven Development, you will be able to build your API for the long-term, while also catching glitches, inconsistencies and generally bad design early on. While this process usually adds 2–4 weeks onto the development cycle, it can save you months and even years of hassle as you struggle with poor design, inconsistencies, or worse—find yourself having to build a brand-new API from scratch.
4. We recommend RAML as a tool to build your spec as it offers the most support for Spec-Driven Development and provides interactive tools that are truly unique. RAML also lets you incorporate design best practices while being able to reuse code and take advantage of design patterns to ensure that your API is consistent throughout.
5. We also recommend that as you’re building your spec you involve your users, getting crucial feedback to ensure it meets their needs, is consistent and is easily consumable. The best way to do this is to prototype your API and have your potential users interact with it as if it was the actual API you are building. MuleSoft’s Anypoint Platform for APIs lets you easily create mocks of your API that you can share with other developers. And with tools like Postman or the API Notebook, users can try out your API without having to write any code.
6. The next step in building APIs for SaaS providers is authentication, or enabling users to access their accounts via the API.  Because you are dealing with user accounts and security, it’s important to understand the different options available to you, such as Basic Auth, OAuth 1, and OAuth 2, as well as the pros and cons of each both from a security, and development aspect.
7. Resources are the primary way the client interacts with your API, and as such it’s important to carefully adhere to best practices when designing them, not only for usability purposes, but to also ensure that your API is long-lived.
8. Next you need to design your methods.  For most APIs you’ll want to implement a standard response format such as XML or JSON, as well as take advantage of existing HTTP method definitions.  One of the most important aspects of designing your resources and methods is consistency, or ensuring that they operate similarly across your entire API.
9. Since APIs are designed to be consumed, it is important to make sure that the client, or consumer, is able to quickly implement your API and understand what is happening. As you build out your API you want to ensure that you not only provide informational documentation to help your developers integrate/ debug connections, but also return back relevant data whenever a user makes a call—especially a call that fails.
10. Understand how to use hypermedia with your API to improve its longevity and long-term usability.

Once you’ve designed and built your API, then you can begin the process of managing it, documenting it, and sharing it with other developers.

Mike Stowe, our developer relations manager, has written Undisturbed REST: A Guide to Designing the Perfect API, which is a comprehensive guide to designing and building the perfect API. Be sure to take a look!