Designing APIs for the customer: analyzing the Unsplash API

The difference between an API and an API product is that products are specifically designed for customers. The essential question of who the customer is for APIs is not as simple as the person or entity who buys it. In fact, many API products are free and yet have multiple customers.

This article breaks down the Unsplash API in order to understand how it was designed with the customer in mind.

The Unsplash API

Unsplash is a photography website that provides high-quality, royalty-free images, classified and searchable by keyword, to anyone. Many of the Internet’s top websites and tools use Unsplash to embed photography into their application experiences. Unsplash’s revenue comes from a mix of advertisements on their platform and a subscription model for their premium offering, Unsplash+. This is a vastly different business model to traditional stock photography websites, which typically charge customers per photo.

The Unsplash API provides programmatic access to the exact same library of photos as its website users. However, the use cases for accessing photos via an API is completely different to accessing photos via the website. Consequently the API’s customers are not the same as the website’s customers.

All API products serve multiple types of customers

An API can be defined as something that enables businesses to communicate with each other programmatically in order to combine their customer value into a single, seamless experience.

From this definition we can extract three distinct categories that all customers will fall in to:

The business customer. The business buys the API and ultimately derives a benefit once integrated with it.
The end-user customer. The end user interacts with the application that was built using the API. Their actions may directly correlate to API calls or the API may be used more indirectly behind the scenes.
The developer customer. The developer integrates the API, and maintains the integration over the life of their own application.

Let's examine the needs of the business, developer and end-user customers to understand what features of the Unsplash API make it customer centric.

The business customer

The business customers of Unsplash’s API are indeed businesses. Unsplash even goes so far as to list over a dozen of them on their website, including Medium, Trello, Squarespace and more.

Businesses typically want to enable their users to include relevant images in their content or customize their own assets with photography. The Unsplash API caters to these needs by:

Providing access to the entire catalog of photos, at scale.
Adopting a royalty-free licence.
Enabling dynamic resizing of images for seamless embedding.

Usage of Unsplash photos via the API scales with the volume of users and the volume of content created by those users. The value of the Unsplash API is not so much in providing access to singular photos, but in providing access to their entire catalog of photos. It’s a small semantic shift, but has enormous implications when coupled with the fact that all photos are royalty-free and can be used immediately. Businesses using the Unsplash API are not just delivering individual photos to their users, but the capability to browse, search and select photos.

Photos provided by Unsplash feel like a native part of the consuming application experience and not a third-party product. This strengthens the customer’s overall experience rather than diluting it across multiple brands. The API delivers this value by providing photos as dynamically resizable images, enabling resizing, cropping, compression, and changing the format of the image in real time by the client.

By enabling photography to be embedded in dynamic, user-generated application content, the Unsplash API differentiates itself from competing photography websites (including Unsplash’s own website), which are limited to providing static content.

The end-user customer

End users are typically creating something such as a form, kanban board, website or article, on a content creation or productivity tool.

It is possible to generalise end-user needs across different types of applications:

Having an impressive and useful default experience.
Enjoying the highest quality image available.
Enjoying fast load times.

Unsplash photos are often used as background or header images of assets. Displaying placeholder images is immensely valuable to authors for them to be able to visualize their final layout. For these use-cases providing a default or placeholder image is critical for the end-user experience to feel simple and lightweight. Most APIs do not allow retrieving unspecified things, however Unsplash provides a “Get a random photo” endpoint for just this purpose.

Unsplash cannot possibly know the intended size that its images will be displayed at, nor the screen sizes of each end user. So rather than providing photos at fixed sizes, which the webpage has to scale down, the API delivers images at any resolution and aspect-ratio, among other parameters. This allows images to be completely optimized for the context in which they are displayed to the end user.

A common issue that can negatively affect a user’s perception of a website is layout shift. This is where the browser partially renders the page before images have loaded, and then re-renders the page once everything has loaded, causing elements to move around unpredictably. This occurs a lot on image-heavy websites, since high-resolution images take longer to load than the HTML document. Unsplash mitigates against this by including compact, placeholder image data in their API. This allows websites to display a blurred version of the image at the final size, then load the high resolution data afterwards, eliminating layout shift.

All of these features could be absent and the Unsplash API would still deliver its business value of providing access to high-quality photos, at scale, royalty-free. However, the end-user experience would not be as great and businesses would have to build equivalent functionality between the API and their end user in order to achieve the same experience. Unsplash is able to deliver a customer-centric experience for the end users of Medium, Trello or Squarespace’s, even though they do not interact with the Unsplash API directly.

The developer customer

Good API products recognize that developers interact with APIs at all stages of their product development lifecycle, not just during development.

During the design stage developers will evaluate the API against other competitors or sometimes consider building in-house.
Before beginning development, developers need to learn how to properly use the API.
During the development stage developers are looking to be as productive as possible using any tools at their disposal.
During the testing stage developers are preparing to go live and will want to ensure their integration behaves the same in production as it did during development.
After going live developers want to ensure their integration performs well and won’t break suddenly.

With the rise of the developer-as-buyer persona, API products that can excite developers and also gain their trust will be more competitive over those that don’t. API products should consider dedicated marketing content aimed specifically at developers as well as providing documentation. Unsplash Developers is the landing page for Unsplash's API product. It communicates benefits, features, social proof and calls to action, and actually contains very little technical information.

When planning an integration, developers are trying to answer two questions:

How do I translate my use case into the API’s concepts?
How do I integrate with the API correctly?

One is a product question, the other is a technical question. API documentation is typically divided into narrative and reference documentation that address these questions separately. Narrative documentation comprises things written in a prose style such as guides, tutorials or how-tos. Reference documentation is designed for lookup and contains detailed information about endpoints and fields, or general topics such as authentication or error handling. Many documentation sites segment narrative and reference content into different top-level navigation sections. Interestingly, Unsplash combines them in the one page, albeit with clearly marked headers.

Providing developers with libraries and SDKs is one of the most effective ways to improve their productivity. With libraries, developers don’t need to learn as many concepts such as how to pass parameters or parse responses. They also benefit from IDE support such as code completion and inline documentation. Unsplash provides libraries in PHP, Ruby and JavaScript and SDKs for iOS and Android.

While libraries, SDKs, great documentation and self-serve tools can all improve the developer experience of using your API, actually making the API itself easier to use shouldn’t be overlooked. In the same way a user interface can provide menus, controls and keyboard shortcuts to achieve the same task, an API can be designed with flexibility, efficiency or both in mind. One of the business values of the Unsplash API is to enable resizing, cropping, compression, and changing the format of the image. In addition to this, the photo object contains pre-built URLs returning the full, regular, small and thumb formats of the photo. These URLs are not strictly necessary as they can be constructed from the raw URL. However their inclusion enhances the developer experience when consuming the photo object.

Conclusion

API products typically have three kinds of customers: the business buying the API’s benefits, the end user using the experience built using the API, and the developer integrating with the API itself. Customer-centric API design considers the customers across all three categories.

The Unsplash API does this well by layering features on top of one another in order to provide value to businesses, end users and developers simultaneously.