28.03.2024

Behind the Scenes of Shutterstock’s API Documentation Redesign

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.

Here, we’ll discuss our principles, approach, and process for building a robust API documentation that helps developers deploy faster.

Why we redesigned our API documentation

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.

Behind the Scenes of Shutterstock’s API Documentation Redesign - Why we redesigned our API documentation

Enabling developers to easily innovate with the Shutterstock API is a key priority because developers are the people who innovate with 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

Behind the Scenes of Shutterstock’s API Documentation Redesign - Role of API documentation

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:

Characteristics of good API documentation

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.

Behind the Scenes of Shutterstock’s API Documentation Redesign - Characteristics of good API documentation

Given Shutterstock’s specific set of API solutions, we focused on five core principles to guide documentation design.

  1. 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.
  2. 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.
  3. 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.
  4. Provides relevant code samples and use cases: Code samples in popular programming languages and relevant use cases for endpoints accelerate the integration process. According to our consumer research, the three most popular languages are cURL, Node.js/JavaScript, and PHP. Additionally, code samples allow us to present the data format and acceptable values for parameters in a concrete way. Wherever possible, we provide code samples that are self-contained and immediately runnable, such as the cURL and JavaScript examples of GET requests. All the developer has to do is store their API token in an environment variable and copy and run the example code. These examples don’t rely on other prerequisites, so they can run without any other code changes.
  5. 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.
Conclusion

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.

Leave a Reply

Your email address will not be published. Required fields are marked *