The usability of an API depends on the quality of its documentation. Here are the principles and approach that steered the redesign of Shutterstock’s API documentation.
At the heart of Shutterstock’s updated developer portal are the improvements we made to our API documentation. As the sole entry point for platforms to innovate with Shutterstock media assets and technologies, optimizing the developer experience is a top priority.
To that end, we created a new API reference page, quick start guide, and API status page in addition to enhancing our existing documentation. Tim McMackin, our Senior Information Engineer who wrote our technical documentation, covers the specific decisions and steps that went into creating a robust API reference. Here, we’ll discuss our overarching principles and process for producing documentation that helps developers deploy faster.
Why we redesigned our API documentation
Image by Kachka
The developer portal is a website and, like any successful website, it must deliver an optimal user experience that provides value. In the context of developer portals, a frictionless developer experience depends on the quality and usability of API documentation.
Enabling developers to easily interact and build with the Shutterstock API is a key priority because they drive the creative utilization of Shutterstock’s API solutions. With improved documentation, we’re aiming to provide fast access to appropriate information so developers can deploy in less time.
Role of API documentation
Image by Kachka
API documentation functions as a practical manual and informative guide to building applications with a particular API. Without proper documentation, application developers are likely to adopt an API slowly, cause excess support costs, limit their integrations, or even choose a competing API instead.
API documentation also serves an important role in marketing an API solution to help businesses make informed decisions. Clear API documentation shows not only what users can do with the API but how easy it will be to integrate. For example, command and response examples can show that the API accepts information in a simple and clear format and returns information and error messages in a useful format.
In our case, the capabilities of the Shutterstock REST API include:
- Delivering images, video clips, and music tracks natively in applications
- Providing access to advanced search including AI-powered reverse image search
- Extending application functionalities such as editing capabilities
Characteristics of good API documentation
Image by Kachka
Good API documentation needs to cater to an API’s specific use cases and integration requirements. It must also anticipate developer needs which can vary significantly across industries.
Given Shutterstock’s specific set of API solutions, we focused on five core principles to guide documentation design.
- Developers first: Developers are the target audience for documentation. Thus, all decisions ranging from UX design to software for generating API documentation must be made in the interest of creating a friction-free developer experience. This focus is why we kicked off and concluded our redesign process with user research on how developers use our API documentation and how they want to use it.
- Easy and fast navigation: The documentation landing page must provide clear routes so users can find the most appropriate section in the documentation quickly. This reduces friction and time in a developer’s first interactions with an API. It also makes it easier for advanced users to refer to the appropriate information.
- Logically organized information with concise copy: We had to make structural decisions about how to organize a large amount of information. Additionally, since our API has many endpoints and parameters, it was important for our supporting copy to be descriptive yet succinct. We decided to structure the conceptual and task-based documentation by our API’s capabilities, such as search and license, rather than by media type (including images, videos, audio tracks, and editorial content). This decision was driven by our understanding of developer intent and workflow when using the Shutterstock API. Additionally, many developers are asset agnostic meaning that they are looking for an API solution to search, license, download, and authenticate — processes that are similar and applicable across images, video, and music assets.
- Supports different levels of engagement with the API: Different developers need different levels of information. Some might be trying out a simple scenario like searching for an image while others may be planning or implementing a large-scale integration. To meet the needs of developers at these different stages, we provided traditional API endpoint reference as well as task-based and conceptual information about API use. For example, we embedded the basics of authentication, searching for media, and downloading media along with the endpoint reference. Developers at an earlier stage of integration will find this information among the endpoint reference and not have to rely on the individual endpoint information by itself. The developer portal also includes a full task-based documentation set for developers who need walkthroughs of the main scenarios that the API offers.
Robust documentation helps preserve developer bandwidth and decrease the time it takes to deploy API integrations. With the translation of the home and partners page into 21 languages, the redesigned documentation improves the accessibility and usability of the SSTK API.
Cover image by Letters-Shmetters