Summary of API Strategy & Practice conference held in Portland from Oct 31 – Nov 2. 

Last week I was fortunate enough to attend, speak, and meet new API enthusiasts at APIStrat in Portland, Oregon. API Strategy & Practice is a series of quality API-themed conferences held throughout the United States, originally organized by API Evangelist and now adopted as a Linux Foundation event.

The 3-day event was a menagerie of API industry expert advice on designing APIs and best practices for their usability. A main highlight was hearing what the Technical Developer Committee (TDC) members had to say on the history and future evolution of the Open API Specification (OAS), the post-Swagger API definition format now open-sourced.

Summarizing a conference of this magnitude is difficult as I could only view a sliver of the three tracks and 70+ sessions. So, in this article I’ll summarize the OpenAPI panel discussion, highlight four talks that resonated with me, and point out some recurring themes around API design. In general, the future is bright, empathy is key, and Open API Initiative (OAI) has the torchlight.

But most importantly, should we rename the pinnacle API description format to that of a cuddly zebra giraffe native to Congo? More on that pivotal question below.

The Data Format Wars Are Over

The OpenAPI Specification received some major focus at this conference. The panel discussion with Swagger creator Tony Tam, OAI ambassador Erin McKean, and TDC members Ron Ratovsky and Darrell Miller shed light on the evolution of the industry and areas for growth for v3 and beyond.

We’ve come a long way since the days of the data format wars, wherein comparisons of formats like XML, JSON, and YAML matched the heated debate over WSDL, SOAP, and REST. Not to mention the rivalry between description formats API Blueprint, RAML, and Swagger.

“We lost several years fighting over the same thing” 
-Tony Tam, Creator of Swagger (now OAS)

Thankfully, things feel more stable now that the industry has largely coalesced around the HTTP API blanketed with OAS (now at version 3) standard. OAS has become a defacto integration mechanism as well as a competitive advantage. Put simply by Miller, “you will get more customers by providing it.”

Where is OAS Heading?

OAS seems to be compatible for describing the majority of web services. However, there is some growing concern on how to extend the spec going forward, specifically on adding ways to describe event based messaging.

While OAI follows the abilities of HTTP-based APIs and thus the HTTP Specification, it shouldn’t describe things that don’t fit into that realm. However, it seems there will always be debate on how to best balance simplicity and complexity.

Therefore, as OAS usage expands, how will it evolve? The TDC has been busy receiving feedback and reiterating to improve the specification, but sees room to evolve certain areas like:

• Event based messaging: Users have requested the ability to describe different types of event based messaging protocols.
• Support for other content types: The OAS is very engrossed in the JSON schema, but technically the API spec is agnostic of format. It could do a better job of catering to Protobuffs, GraphQL queries, and other content types.

The OAI has set a solid foundation. But to enable the average developer to leverage its full potential, we really require a community of third party tool implementations. Code generators, documentation generators, visualizers, and niche libraries will propel usage into new domains.

“OkAPI” Has Our Vote

Will, an Okapi calf recently born at Brookfield Zoo in Chicago Illinois. Hope to see him at APIStrat 2018!

Just look at this cuddly zebra-striped baby okapi. Okapis, of the Giraffidae family, are native to a very small region in Congo in central Africa. They could very well be the mascot our industry wants. Our industry needs.

Brought up at APIStrat: Should OAS be renamed to OkAPI?

Conveniently named with the API acronym in place (guess the Congolese were the first RESTafarians), an Okapi mascot could be a cute visual companion to a spec that currently lacks theme and personality.

While renaming “Open API Specification” to “OkAPI” seems humorous at first, there’s strategy here. Visual aids can unite technology to make it more memorable, thus more widely adopted. This is reminiscent of the ram in RAML.

Also, OpenAPI Specification is a mouthful, whereas OkAPI flows off the tongue easily. We’ll just have to decide what the exact pronunciation is: oh-kah-pee  or oh-kay-API?

Okapi is derived from the pygmy word O’Api which, when spoken by pygmies, sounds like okapi. – San Diego Zoo

Of course, a brand redesign this massive is far-fetched, and perhaps this was just a joke. Any change will ultimately be the OAI’s call. But for the record, Okapi – or OkAPI – has my endorsement!

The Future Is Bright

Widely shared satire on Microsoft’s legacy silos

Day One saw some awesome keynotes. Opening the conference was Yina Arenas, Principal Program Manager at Microsoft. She first shared a popular piece of satire on enterprise organizational structures. Sadly, until recently, Microsoft didn’t have the best reputation for inter-departmental collaboration.

Without patterns and consistency, Microsoft’s products were super siloed. Collaboration was a big mess. Thankfully, an API-first initiative was born from the bottom up.

By agreeing to standardize with REST, Canonical ids, and API governance, their teams successfully broke down silos, and translated customer passion into customer value. This culminated in the Microsoft Graph and subsequent API guidelines. Guns no more!

Have Empathy. |Gains| – |Losses| > 0

A common word we kept hearing at this conference was “empathy.” It’s inspiring to see boundaries diminish as the API space coalesces on common ground. As your mom probably told you, working together is better for all. And, having empathy in business, as it turns out, might actually be scientifically proven to increase success for all involved.

In Sarah Novotny’s talk Open APIs and the Power of Positive Sum Games, she discussed how boundaries are eroding, and a lot of that is founded on empathy.

“We’re at an inflection point in our industry now. The future is bright”
-Sarah Novotny

As API programs place importance on design, usability, community engagement, and developer experience, empathy has become a definite business value. As APIs share information, empathy is the bedrock of these transactions. Novotny equates this to positive sum game theory; essentially if we work together, the positive gains outweigh losses.

Open APIs and composable technologies are benefiting the entire ecosystem. Darrell Miller, a staunch hypermedia advocate who ironically fought against Swagger in its early day, is now a core OAI TDC member. He reminds us not to “ignore successful things for theoretical reasons.” Combining best of breed approaches, and having them work together, is much better than living in obstinate opposition.

#APIStrat “empathy” talk mention count: 5 📈

— Taylor Barnett (@taylor_atx) November 2, 2017

Reuse != Efficiency

In the software world, code reuse is often hailed to improve efficiency and decrease development effort. Though code reuse is typically viewed as a positive, it might not be the golden solution.

In his talk The Damning Fallacy of Assuming Reuse Is The Road to Efficiency – Leveraging Microservices for Experimentation (slides), Irakli Nadareishvili of Capital One sought to set the record straight.

The Jaggedness Principle argues that no person is completely “normal” – we all have a multitude of individual characteristics. Therefore, reusing average requirements across the board can result in bad usability. Take a story from 1940s era airplane construction:

“The cockpits were originally designed around the average range of 10 body measurements taken from a population of 4,063 pilots. But because no single pilot met all those criteria, they ended up with a seat which actually didn’t fit anybody.” -Qi.com

Since human proportions are variable, the seats were useless to nearly every pilot who tried them, and had to be trashed. The moral of the story for microservices? Be selective in your reuse:

“Try to avoid designing for average use case to maximize use”

Just because mean averages exist doesn’t mean they should be followed religiously. Standardize protocols and contracts, and share common vocabularies. Whereas reuse of widely adopted services is recommended, Nadareishvili feels that custom libraries and certain data models should not be reused.

7 Important API Design Trends

How is API design evolving with the advent of new trends like bots, IoT, and event-driven apps? Are we correctly mapping modern client-server transactions in the design of our APIs?

Put simply, API design is changing. In his talk API Design in the Age of Bots, IoT, and Voice (slides) James Higginbotham charted out 7 areas that are altering the way we design APIs:

1. Hypermedia and HATEOAS
2. Event subscriptions
3. Capability-driven API design
4. Content negotiation
5. Front-end context APIs
6. On-device APIs
7. Bots as next generation APIs

Most web APIs are still stuck in the land of CRUD (Create, Read, Update, Delete), which doesn’t reflect Natural Language Processing at all. Higginbotham reminds us that API design is not your database, but is really an architectural concern that combines, business, product design, and external technology.

API design is more than IT, it affects all aspects of an organization #apistrat @launchany pic.twitter.com/zFHrMZsMf2

— Bill Doerrfeld ⚙ (@DoerrfeldBill) November 1, 2017

Including a choose your own adventure style design with hypermedia could make applications more flexible, and context-based interactions can be achieved using content negotiation. In general, new trends like Alexa commands or on-device APIs are involving new client-server relationships that could beckon a capability-first approach to designing new API interaction layers.

Great Focus on API Usability at APIStrat

The panel discussions and 4 sessions above were only the tip of the iceberg of knowledge presented at APIStrat. Much was said on gRPC, JSON Schema, creating API style guides, improving documentation, and other practices for A+ developer experience.

To round things out, more insights on API business modeling and monetization could have empowered some new goers, but I’m sure that other APIStrat events will spotlight those topics in the future.

Cheers to the organizers and sponsors who made it possible, and for the speakers for offering such engaging talks. This was also the first year APIStrat was organized by the Linux Foundation, and they did a great job with structure and clear scheduling. Hats off to all who participated. The #APIStrat community rocks!

Resources:

• Full APIStrat 2017 Portland Schedule
• Open API Initiative
• Featured sessions (In order of appearance):
  • From Guns to Graphs. Yina Arenas.
  • Open APIs and the Power of Positive Sum Games. Sarah Novotny.
  • The Damning Fallacy of Assuming Reuse Is The Road to Efficiency – Leveraging Microservices for Experimentation. Irakli Nadareishvili. Slides.
  • API Design in the Age of Bots, IoT, and Voice. James Higginbotham. Slides.