# Net API Notes for 2021/08/25 - Issue 172

Net API Notes is a regular, hand-curated digest of impactful news and analysis for busy API practitioners. Are you reading this on the web and not subscribed yet? Sign up today and be the first to get ad-free, actionable info delivered weekly to your inbox.

For some of my readers, the kids are already back in school. The past few weeks have been a flurry of registrations, checklists, shopping, and final summer plans for others, like myself. Regardless of which camp you're in, I hope you and yours have a healthy and happy return to in-person education.

Speaking of education, it is time for another edition of Net API Notes!

NOTES

HOW SLACK DESIGNS APIS

STRAT / DESIGN / DOC / DEV & TEST / DEPLOY / SECURITY / MONITOR / DISCOVERY

Saurabh Sahni and Taylor Singletary published a great piece on the Slack engineering blog entitled, "How We Design Our APIs At Slack". They cover not only Slack's design process but also the six design principles their APIs need to adhere to. Those principles are:

• Do one thing and do it well (Single Responsibility Principle)
• Make it easy to get started (Time to First Hello World)
• Strive for intuitive consistency
• Return meaningful errors
• Design for scale and performance (pagination, filtering, avoid large nested objects, rate limit)
• Avoid breaking changes

Not every company is Slack. However, the guidance provided here is broadly applicable to a wide range of situations.

1PASSWORD ON SWITCHING TO PLATFORM-DRIVEN DEVELOPMENT

STRAT / DESIGN / DOC / DEV & TEST / DEPLOY / SECURITY / MONITOR / DISCOVERY

Michael Fey shared a slightly different type of API story in his piece, "1Password 8: The Story So Far". Many times, especially when we talk about migrating monolithic codebases to microservices, we speak about idealized, simplified abstractions. In discussing the history of 1Password, Michael provides an example of how real platform needs drove reorganization of codebases and team structures to accommodate them. This included moving from a unique technology stack per platform to a centralized core set of features exposed via APIs

"We began exploring options for consolidating the non-user interface portions of 1Password into a single codebase that we could insert into each of our apps. The goal was to replace those four separate technology stacks — each with their own idiosyncrasies, differences, and frankly, bugs — with something that allowed us to move faster, together. With a couple false starts and technology changes under our belts we finally caught our stride at the beginning of last year. A small team, using existing pieces of various apps and projects, put together a proof of concept of a brand new 1Password app running on top of what we now call the 1Password Core."

I've seen this progression again and again with successful software projects: at some point, it becomes necessary to separate the core business rules from the experiences to be delivered. That can be a difficult transition; the core team can feel estranged from the customer, the 'experience' teams might feel as though the impact of what they're responsible for is now dependent on others. Higher level managers have more coordination across both.

While it isn't directly related to the technical delivery, navigating this difficult stretch is of vital importance for more sustained API success.

WHAT ANALYZING 200,000 OPENAPI DESCRIPTIONS TELLS US ABOUT APIS

STRAT / DESIGN / DOC / DEV & TEST / DEPLOY / SECURITY / MONITOR / DISCOVERY

Postman challenged the Open Technology Group to expand API industry analysis and shared insights; it is an aspect that makes working within the group exciting. Not to toot our own horn, but our own Mike Ralphson just shared the latest example, "What We Learned from 200,000 OpenAPI Files".

It is one thing to know and use a standard, like OpenAPI. It is a very different thing to see how that standard is used across an entire industry. And what does the industry do with OpenAPI?

• 79% of the API definitions were valid according to oas-validator
• Just over 6% of the APIs include a logo URL in the x-logo extension property, as popularized by ReDoc and APIs.guru
• Approximately 2% of APIs have a publicly available /status endpoint
• Nearly 4% have a /healthcheck or /ready endpoint
• Only 2% of OpenAPI definitions in the wild are PetStore related
• Each API has, on average, 37 paths
• Each API has, on average, 51 endpoints (or 1.4 methods per path item)
• Each API has, on average, 38 distinct query parameters across all operations
• Each API has, on average, 33 schemas defined, or 0.65 schemas per operation
• The combination of basic and/or apiKey security is most common, followed by no security, apiKey solo, basic, oauth2, oauth2 and/or apiKey, and other http mechanisms

More in the post!

MILESTONES

• Postman (my employer) closed a $225 million Series D round of funding. Sadly, contrary to rumor, that money is not earmarked for my milk and cookie rider.
• Not coincidentally, Postman is hiring! Are you in an engineering or architecture role but looking to work more directly with customers? Have customer service or sales experience? Check out our solutions engineering role.
• API analytics company Moesif received an additional $12 million in funding. The investment is said to grow user behavior insights on API usage.

WRAPPING UP

Net API Events is available online. I'm thinking long and hard about whether to begin including domain-driven design meetups, as there is some very applicable conversations going on there. What do you think? Let me know.

I'll end with thanks to my Patreons. You are the reasons this newsletter is free of advertising, information selling, or paywalls. Thank you..

Till next time, Matthew

@libel_vox and matthewreinbold.com

While I work at Postman, the API comic creators, the opinions presented above are mine.