This is part seven of the API design best practices series. Read part one of the series.
Looking Back
Unfortunately, this series of API Best Practices has come to a close. Over the last several months we’ve taken a look at how to design a flexible, extensible, and usable API. These steps included:
1. Planning Your API – The first and most basic step, is understanding what it is that you’re actually building. Understand what your customers want (this means involving them), understand what different types of APIs there are out there, and why you are building the kind you are (REST, REST-like, SOAP, RPC). Lastly, it’s important to map out the functionality that your users need – and to not get stuck in a resources/CRUD mindset when doing so.
2. Utilizing Spec Driven Development – Using a spec like RAML to model your API, lets you get an immediate visual representation of what it is that you’re actually building while taking advantage of code reuse and design patterns for consistency. Keep your users involved and prototype (mock) your API for them to test out using tools like the API Notebook. Keep making revisions to your design until you have a solid foundation and have fixed 99% of the design flaws. Then start building!
3. Using Nouns for Resources – Keep your resources versatile and flexible. By using nouns you can stay true to REST principles and avoid tightly coupling your resources to methods or actions. Remember that you generally want your resources in the plural form (users) and they should map to the objects or areas that your clients are trying to manipulate (ie: /users to modify users).
4. Following CRUD and use HTTP Action Verbs – By thinking of actions in a Create, Read, Update, and Delete format you can take advantage of the HTTP Action Verbs or methods and make it easier for developers to utilize your API. Be sure to understand the difference between POST, PUT, and PATCH – and when to use which.
5. Using JSON when possible – JSON is more compact and more widely supported by languages than XML, YAML, and other formats. However, some clients may require other formats, such as XML – which is where the Content-type header comes in!
6. Using the Content-type header – Even if you’re only planning on returning back one format (such as JSON), the Content-type header gives you the flexibility to add in more formats down the road and support multiple client’s needs without having to modify your API.
7. Hypermedia… Hypermedia… Hypermedia – Yes it’s a challenge, but by adding hypertext links to your API result with a standardized format such as HAL or JSON API, you’re giving developers the tools to better understand and discover your API, while also providing them with the application state (can an item be edited, deleted, etc).
8. Utilizing HTTP Status Codes – Tell your clients what’s happening, when things are successful (200, 201) or when they’re not (304, 400, 500).
9. Providing descriptive error messages – When something doesn’t work, don’t just tell them it didn’t work, tell them why. Take a look at some of the more popular error messaging formats including Google Errors, vnd.error, and JSON API’s error format.
10. Remembering that SDKs can be part of the solution, but they can also be part of the problem – Don’t expect an SDK to solve your problems or reduce your workload – instead look at them for what they are – a tool to help developers get started more quickly with your API. And a tool that you’ll need to be maintaining.
11. Taking advantage of an API Management tool – such as MuleSoft’s Anypoint Platform for APIs. API Managers are designed to protect and help scale your API– keeping threats out and protecting you from both unintentional and malicious attacks on your API– while also handling authentication, provisioning, and throttling to keep your API running optimally.
And that brings us to number 12… one of the best pieces of advice I’ve ever received for building an API:
Keep it Simple. As you design your API there will be temptation to do fancy or “innovative” things within your API – don’t. Instead, remember that you are building a foundation for future development. The fancier you get, the more likely you are to limit yourself or fall victim to bad practices. Instead, the simpler you keep your API, the longer you’ll be able to extend it, and the easier it will be for your clients to utilize. Simplicity is key.
Remember, building an API is easy… but designing an API that lasts – that’s the hard part.
Interested in learning more? Discover Anypoint Platform for APIs or get started with API Management with API Manager
Want to learn more about designing your API? Stay tuned to @MuleDev, and follow @ProgrammableWeb for all the latest news in the API ecosystem!
