Part 3 Contextual API design

 

Reading the first two parts of this book, you have learned to design APIs that make sense for consumers—ones that are easy to understand and easy to use without even thinking about it. Is that all you need to design APIs? Absolutely not. Thinking that an API designer’s job ends here would even be a terrible mistake. Stopping here would inevitably result in the creation of unfit and even dangerous APIs. Indeed, we designed APIs without much consideration to the whole context surrounding them:

  • Is our design totally secure given the intended functions of the API and how it will be exposed to users?
  • Will it actually be usable by, let’s say, a mobile application on a poor quality 3G network?
  • Is our design actually the best one for our targeted consumers?
  • Is it actually implementable upon our existing systems?
  • Is our design so good that it does not need any documentation?
  • Is our design totally consistent with all our other APIs?
  • What if we want to update it once it has been pushed into production—can that be easily done?

All these questions must be answered. As API designers, we must take the whole context surrounding an API into account when designing it. Hopefully, you will learn to do so in the following chapters.