Before designing an API, model your API: guide

API modelling is a crucial preliminary step in designing efficient APIs, as it helps clarify the specific problems an API should solve and informs the choice of interaction styles such as REST, GraphQL, or gRPC. James Higginbotham emphasizes that API modelling is an iterative process that involves understanding the needs of participants and desired outcomes, which can then be decomposed into actionable steps. By starting with API modelling rather than database design, developers can avoid creating APIs that focus too heavily on database structure rather than user needs, leading to better communication and naming conventions that align with a shared understanding between developers and stakeholders. The process involves identifying participants, desired outcomes, and mapping these to specific steps, before capturing these as candidate resources and actions within an API model that can be validated against requirements. Effective API modelling incorporates best practices such as involving subject matter experts early, using standard data formats, and ensuring thorough validation to ensure that the API meets user needs and is easy to consume.