When Designing APIs, Good Path Matters

The 1946 biography of Woodrow Wilson includes an interesting quote:

A member of the Cabinet congratulated Wilson on introducing the vogue of short speeches and asked him about the time it took him to prepare his speeches. He said:

“It depends. If I am to speak ten minutes, I need a week for preparation; if fifteen minutes, three days; if half an hour, two days; if an hour, I am ready now.”

Similar sayings can be found from other great speakers:

I rarely have ample time to prepare five-minute speeches, but I can go and speak an hour at any time.

-Abraham Lincoln, President of the United States of America

“If it is to be a minute speech I shall need four weeks in which to prepare, if a half hour speech, then two weeks, but if I am to talk all day I’m ready now.”

-Rufus Choate, Senator from Massachusetts mid 1800s

The wisdom being shared in these quotes is that when every word matters, and the message needs to be concise and free of anything extraneous, ample time is required to engineer the message.

When you are crafting the structure of your APIs, especially those to be exposed externally to the public, the same advice applies.

Setting security patterns aside for this article, our focus in here is paths and responses.  And to practice what we are preaching; this article will be short.

If your paths and responses closely align with the related business or subject matter of your APIs, then two benefits manifest themselves:  

  • Developers that understand your business model will find using your API intuitive
  • As the business model evolves, it will be easier to evolve the API in like manner

A quick example.

SHOP.COM carries millions of items including exclusive products along with regional and national brands.  SHOP.COM offers many consumer benefits with unique programs and services.  SHOP.COM also has a family of sites, including motivescosmetics.com, isotonix.com, and tlsslim.com to name a few.

When we designed our public API, we had to decide what was the center focus of our business from the perspective of application innovation.  Was it our sites, our products, our programs like cashback and Shop Local and so forth?

We decided that our external partners would be best served with a “products” centric view of our business.  As the design was refined, the Endpoint paths became simpler and more concise, until we were practically down to one “/products”.

That endpoint, complemented with parameters and responses that align with our business model (our sites, our countries of operation, languages, the categorization of our products, and so forth), resulted in a very intuitive API for developers to exploit.  Also, it has been easy to evolve the API, adding new ideas and features, without threat to the base contract of the API.

The time we took with our path and response engineering continues to pay us back over and over.

As a final note, speeches and articles both submit to the tenet above.  Writing a short article that says everything you wish to say, and says it well, took more time than I thought it would.

Be sure to read the next API Design article: What is an API Fragment?