DX, API Design & Documentation

Scaling Best Practices in API Design


Serah Njambi Kiburu is a senior developer advocate at Spotify. My team works on something we call Spotify for developers. Spotify for developers is where we open up all the APIs you want developers to use to extend services to us. This article discusses scaling best practices in API design.

When we look at a picture or art, it can be interpreted in any form, and there’s no wrong or right answer. You can share whatever interpretation you carry with you, and that is how it is scaled.

When we consider culture, there are multiple languages in one region, let alone across the continent, but some words have a universal understanding. Every language has its constructs and constraints, but there is wiggle room to express yourself, localize, and bring people into your context.

When we think about API design, and the ways we want to scale into different locales, we want to think of rules that we want people to stick to but also give them some wiggle room. But if you can’t, that’s okay. We have to keep designing our APIs so that they will scale in the different environments they will be used. When designing these APIs, we may not know all the contexts they’ll be used in.

API Best Practices

  • API-first is a good approach to adopt in API design. It hyper-focuses on developers. You need to have them at the core of everything you’re designing and developing your API.
  • Modularity – Your API components should be independent.
  • Standards – When designing your APIs, you must consider your end users. Using specs, like the open API spec or known standards, is good so that people do not have to learn your system from scratch before adopting and using it. If you want to build your own standards, you have to be very careful because, in this case, you’re starting from a challenge that existing standards have not resolved. The challenge then becomes that instead of unifying everything you wanted to, you usually end up fragmenting things a bit more. So be careful about that.
  • Documentation is a big part of API design and development. Document everything right from your initial conversations with your team, work your way through to development and documenting every process, and decide what is just for internal use and what part of it goes out externally. Err on the side of too much documentation.

Scaling API Best Practices

  1. Know your users. Persona profiles and user stories are an important source of information about your API’s users, their needs, and the contexts they work in. You need to engage user researchers to help you think and talk to your potential and existing stakeholders and make their persona profiles. These will help you track why you made certain decisions at different points in time and the reasons why you’ve made updates over the season.
  2. It’s always a good day to learn more. Lots of us have been in the industry long, so I wager that with time, it’s easier for us to err on the wisdom of experience we’ve had and forget to learn from others. It’s always a good day to find a book, attend a conference, learn from people, and understand trends. You should keep up with the tech as it evolves because then you can keep developing relevant things, both from the perspective of the people who will use it and based on best practices in the industry.
  3. It is in sharing that we learn. Don’t just learn; share what you learn. Create a learning environment within your team. Encourage talks and workshops. Make room to talk of challenges and failures.
  4. Publish your best practices. You should publish your best practices internally or externally. It need not be a physical print; it can also be blog posts or other media.

Serah Njambi Kiburu
Senior Developer Advocate at Spotify

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture