Have A Clear Vision For Who Will Be Using The APIs

One significant mistake that we see API designers, developers, and architects make over and over again, is not having a clear vision of who will be using the APIs they are building. Defining, designing, delivering, and operating an APIs that are based upon what the provider wants over what the consumers will actually need. Using protocols, ignoring existing patterns, and adopting the latest trend that have nothing to do with what API consumers will be needing or capable of putting to work.

When operating your APIs, make sure you always get to know your consumers, and always be thoughtful about giving them more control with query languages like GraphQL and Falcor, allowing them to define the type of experience they want. Work to have a clear vision of who will be consuming an API, even if you don’t know who they are. Starting simple with basic web APIs that help easily on-board new users who are unfamiliar with the domain and schema, while also allowing for the evolution give power-users who are in the know, more access, more control, and a stronger voice in the vision of what your APIs deliver or do not.

There is not a single API design approach that will work in all situations, for all consumers. This is why we should have a diverse API toolbox, especially across large enterprise organizations. Not all APIs will be the same, and not all applications build on APIs will have the same needs. Stop looking for a single approach or philosophy to address your API development needs, and always begin with a RESTful approach, but quickly be able to access when your API consumers might need more specialized approaches that help them get what they need with as little friction as possible. Your enterprise-wide API design vision should always reflect who will be actually putting your APIs to work in their applications.