The size of the API economy is at an all-time high, with ProgrammableWeb reporting that there are over 17,000 APIs available on the web. The increasing demand for APIs has created a need to apply key API best practices.
But before you jump into creating APIs, in order to follow API best practices you need to ask yourself some questions. Why are you building an API? How should you mock your API? Why should you use nouns as resources? How should you implement hypermedia? How can you better manage and secure your APIs? If you want to know the answer to these questions, then explore our API Best Practices Series––a complete guide to planning, designing, and managing APIs.
The guide covers a range of topics, including:
All great things start with a plan, including building an API. Read this section to learn why identifying why you are building an API is key in enabling you to understand the types of data and methods your API should have, how users can utilize your API, and how you can think ‘long-term’ when building an API.
Part 2: Spec-driven development
The key to building great APIs lies in employing spec-driven development by defining each API in a flexible, standard specification. Check out this section to learn the importance of spec-driven development and how you can use tools like API Designer to better define and mock APIs.
How can you ensure that your API is flexible, extendable, agile, and accessible to other developers? This section answers this question by demonstrating the value in using nouns – not verbs – as resources, applying CRUD, using JSON, and other best practices.
Hypermedia is an extension of hypertext––something you may recognize from HTML. In this API best practices section, we dive deep into the world of hypermedia and cover three topics. Read these sections to learn:
- Sub-series 1: The most common arguments for and against hypermedia
- Sub-series 2: The state of hypermedia specs
- Sub-series 3: The types of specs available and their pros and cons
Response handling is the next logical step after planning, building, and designing your API. Read this section to learn how to use the appropriate HTTP status codes and return descriptive error messages on failure in order to better understand what happens with your API calls
In building APIs, you are creating a vehicle for developers to access specific data and services. It’s not enough to build and design this vehicle, but also create the guidelines to ensure that everyone is driving the vehicle safely. Explore this section to understand how to better secure and manage your APIs in order to mitigate malicious users and other vulnerabilities.
Building an API is easy, but designing a useful, secure, future-proof API is not. Check out the final post in this series for a high-level summary of the top best practices from the series and what tools you can use to get started.
Want to learn more? Check out Undisturbed REST, a guide to designing the perfect API.
