API Specifications Conference 2020 Recap

Last week, I enjoyed being the API Specifications Conference’s program chair, with over 300 attendees in attendance. In its second year, it is the only conference that focuses explicitly on API specifications and standards. While we decided to take the conference virtual days before almost signing a venue contract, I’m happy to say that attendees were thoroughly engaged, and many great discussions were had. At Transposit, we are consumers of many APIs in our platform, so conferences like the API Specifications Conference are an excellent opportunity to learn from other API producers and consumers.

I noticed a few trends in some of the talks and conversations around API design reviews and governance, socio-technical or “human” problems, and topics that go beyond “why are specifications important,” which has taken up a lot of space in previous API specifications content.

A big topic over the past few years has been, how do you scale the use of API specifications within large organizations? Yes, API specification documents are great, but there are often pain points discovered when scaling adoption across large organizations.

Managing API specs at scale#

Jay Dreyer (Lead Engineer, Target Corporation) talked about how they’ve been using OpenAPI for a few years at Target and managing 1200+ specification documents, including some of the solutions they’ve found to encourage adoption across the engineering organization:

More on API design reviews#

There’s been a lot of progress with human-in-the-loop automation in these areas. For example, some teams use automated linting based on style guides for the first stage of an API design review followed by a human reviewer who would cover things that are harder to write into a style guide and give final approval. These might be done by an API team, committee, or architect. It’s a great example of offloading some work to an automated process while still having humans part of the loop. When I helped release Spectral last year, the idea of linting an API specification document was still gaining traction. I’m happy to see it is a lot more popular, and folks are integrated into their processes.

Other talks about this process include “The Augmented API Design Reviewer” from Arnaud Lauret (Natixis) and “The Vocabulary of APIs: Adaptive Linting for API Style Detection and Enforcement” from Nicole Gizzo and Tim Burks (Google).

"People problem and technical adoption problem"#

The keynote panel with moderator Erik Wilde (Catalyst, Axway), Mike Amundsen (Amundsen.com, Inc.), Yina Arenas (Principal Group Program Manager, Microsoft), Adam DuVander (Principal Developer Strategist, EveryDeveloper), and Gail Frederick (SVP Engineering, Salesforce Developer Experience, Salesforce) was my favorite part of the whole conference. It was particularly significant because of the discussion on the problem of standardization at large organizations like Microsoft and Salesforce. Often inconsistency across APIs within an organization, like when you have 100+ APIs, causes a lot of pain for developers. As Yina Arenas said, it is both a “people problem” and a “technical adoption problem.”

For the users#

Mark Nottingham’s (Senior Principal Engineer, Fastly and Chair, IETF HTTP Working Group) keynote touched on the idea that often, our technical decisions around specifications and standards affect end-users, which he’s expanded on in a recent blog post.

He also talked about how to get involved in the new HTTP APIs Working Group (HTTPAPI) that should be approved soon. You can sign up for the mailing list here. My favorite part is that in the end, he said, “...if it isn’t well connected to real world practice and a diverse community, I will be the loudest person in the room arguing that the group should be closed down. We don’t deserve another WS-*.”

Humans and machines#

And then there was Lorna’s keynote about playing to our strengths. Machines can take verbose and unwieldy API descriptions and process them. From an API description, we can get things like mock servers, code generation, and other machine processes. We still need to learn more about how to lean on machines for their skill sets and lean on humans for API design, developer experience, and creativity.

Conclusion#

Overall, I’m excited to see the direction that the API specifications community is going as a whole, both from a tooling and cultural perspective. The conference was a great example of this progress.

If you are curious to dig in more, you can check out the rest of the API Specifications Conference talks in this Youtube playlist.