Spotify’s New Podcast API: From Design to Launch

March 25, 2020 Published by Spotify Engineering

This week, we launched our podcasts API. This means that our new API is now open to third-party developers! Third-party apps can now connect to Spotify and manage a user’s podcast library, search our podcast catalog, or fetch detailed information about podcast shows and episodes.

We’re excited to see the apps and mashups that developers will build using this new functionality.

Launching a new API at Spotify is an iterative process and the Web API team had many considerations to think about when building the new podcast endpoints. In this blog post, we’ll shed some light on the process of designing and building a new Web API for the Spotify developer community.

API dogfooding at Spotify

Spotify doesn’t offer public Web APIs for all the features that you see in our iOS and Android apps. The SDK team selectively releases developer functionality based on feedback from internal engineering teams and members of the developer community.

Web APIs at Spotify commonly begin as an internal-only product, available for engineers to use in Hack Week projects and Spotify-developed apps. This was the case for our podcast APIs, which debuted in 2015 with a small feature set. The first features included the ability to list episodes and shows in a library, and the ability for apps to read podcast metadata: information about the shows and episodes in the Spotify catalog. These features enabled podcasts to appear in open.spotify.com, our web interface for Spotify users.

Spotify’s Web API team creates and manages the API design patterns that we use in our consumer web APIs. While improving our podcast API, the team created a proposal that documented the design of their new endpoints. Sharing API documentation in advance of writing code is an effective way to gather feedback quickly from partners and internal stakeholders.

The team had many competing factors to consider:

  • Backward compatibility where podcast functionality has been added to existing Spotify API endpoints. For example, our Player API exposes the currently playing song. We’ve added a query parameter, so that clients that are able to consume podcast objects can opt in to receiving information about episodes that are currently playing.
  • Consistency with Spotify’s other web APIs. Error codes, request and response payloads, and authentication flows should feel familiar for developers who have used other parts of Spotify’s existing Web APIs.
  • Consistency with Spotify’s app terminology. Someone who is new to the Spotify API should be able to easily identify how features in the app are associated with API features.
  • The verbosity of our API response payloads. For example, our new API endpoints can provide an episode object or a simplified episode object depending on the situation. The team has to carefully consider which fields belong in the simplified payload and which fields can be exclusive to the episode object.

Scaling for external partners

The Web APIs are consumed by millions of users every day, in a diverse range of apps and hardware use cases. Before sharing a new API with external partners, the API team sets up monitoring for their service using Grafana and Lightstep. This monitoring can trigger alerts and page a team member on PagerDuty in the event of an outage or degraded service, providing enhanced ability to scale for our partners.

Why we’re especially excited about this podcast API

Launching this podcast API is very meaningful for Spotify right now as we continue to delve deeper into creating value in new ways for listeners with podcasting. We are excited to unleash the creative power of the developer community and allow the expansion of Spotify into areas we’ve yet to explore.

Optimizing for the developer community

Prior to this week’s public launch of our podcast API endpoints, we made this API available to a select group of Spotify partners who were building external integrations. Those developers gave us additional feedback that we used to refine the design of the API and improve our onboarding experience for developers who are using the podcasts API for the first time. In particular, the team focused heavily on writing clear technical documentation for API consumers to read when writing their apps. At Spotify, API documentation is written by engineers, technical writers, and the developer relations team, and we edit and review docs together through GitHub pull requests.

Making the API publicly available doesn’t mean that we are finished with improving it. For the next six months, our API team plans to continue to monitor feedback on this new functionality closely. We hope to improve the API based on what we see and hear from the developer community. If you have any feedback on the API that you’d like to share, be sure to get in touch. You can reach us at podcasts-api-beta@spotify.com

By the way, our web API team is hiring! If building the audio platform of the future sounds interesting to you, then check out our job postings (and more Spotify careers) on spotifyjobs.com


Tags: