11436 SSO

API Design: Demystifying Modeling

May 06, 2013

We did a third edition of our webcast on API design, where we drew upon the discussions and implementations with hundreds of crafters and technologists, which helped shape our API design thinking in the twelve months since the previous edition of RESTful API Design.

Grounded in the premise that the design of an API communicates how app developers will use it and that the API is an extension of a brand, one of the first topics we tackled in the webcast was API modeling.

“The real issue is about design: designing things that have the power required for the job while maintaining understandability, the feeling of control, and the pleasure of accomplishment.” ~Donald Norman

Good design is about supporting rich capabilities while maintaining high usability. When building a cathedral, the design is complex but the outcome is a thing of beauty. Our goal is to show how to create seamless designs that are pleasant to use.

Let’s begin by recapping our initial discussion about design, which is covered in Apigee’s eBook on Web API Design and then discuss API modeling. Our initial discussion about API design centered on URL design and we hinted about versioning, errors, and client considerations, as summarized below.

Develop a Model

Designing API resources and representations begins with a basic understanding of domain modeling. We sometimes use the Unified Modeling Language (UML) to create a visual model of object-oriented software systems. However, even a low-tech napkin sketch can help get the conversation started. Resources, data fields, and relationship mappings are all helpful down the road if discussed and documented up-front.

To start, gather all the stakeholders involved in the API team, including marketing folks, business analysts, software engineers, and key business people. The goal will be to build a conceptual model of the API that will eventually be translated into working software. Include language for any surrounding processes that might be related to this initiative: background jobs, ETL processes, etc. (Image Source: http://www.flickr.com/photos/brent_nashville)

Develop a common language, a glossary of terms that will appear in the API. Once a ubiquitous language is established, it’s important to use these terms everywhere: in resource names, identifiers, data fields, and documentation. This reduces confusion caused by mental context switching when speaking to different audiences about the API, including app developers.

Using a common language, piecing together what should be exposed via the API. Resources should emerge naturally from conversations with domain experts. Start with top-level resources and work down the list. Take into consideration all the near-term business projects and don't forget that some resources may only be exposed to a few individuals with the proper permissions.

Define Success

An API Team defines what makes their API successful. Defining acceptance criteria early ensures the API gains alignment among all business units with a stake in the game.

Criteria may be in terms of:

  • Developer Adoption
  • Usage Metrics
  • Server Performance
  • Business Revenue
  • Sales Leads

Write acceptance criteria with terms that are understood and valued by all members of the API Team; ubiquitous language works. This way, criteria may be eligible for automated testing by the technical team, which gives the team something to celebrate and acts as an outline for communicating success to key stakeholders.


An API represents your organization and your brand, so make sure all stakeholders are present for key API decisions. Going solo often leads to a late realization that marketing doesn’t use the same terminology or the discovery of resource challenges. In reality, most problems in modeling are not technical in nature. When business processes are complex so is the API that supports them.

Continue to iterate. In most cases, a shared language reflects complex relationships that evolve as information is gathered to further the success of your API program and the latest version of your API design.

To join the conversation around APIs, check out the API Craft Google Group.

Next: Deciphering Security

Scaling Microservices