API Specifications Update for July 30th, 2021
30 Jul 2021
I try to stay up to speed with what is happening across the leading API specifications each week. The evolution of OpenAPI, AsyncAPI, and JSON Schema is important to what I do at Postman, but also to the wider API space. I find it helpful to understand what is happening across each of the API specification communities, and I wanted to also find a way to share what I am seeing with everyone else. Providing a single digest of what is happening, without having to do all the work I am doing each week. While I am sure there is much more going on that I am not tuned into, here is a snapshot of what I see happening.
The OpenAPI initiative held its weekly technical developer community (TDC) meeting on Thursday, and you can find the agenda for the session here. In addition to the weekly TDC meeting, there is growing cadence of special interest group (SIG) meetings emerging with the security and travel SIGs both meeting this week. The groups are still getting going and establishing their meeting cadence and agenda. As I gather more links and resources I will make sure and share them. The most I have right now is a link to a pull request to add a SIG page to the OAI specification repository. Mike Ralphson (@permittedsoc), Frank Kilcommins, and I are also holding open office hours across all three specs every Thursday at 8:00 AM PDT, and you are welcome to join in--this update is the result of the work occurring within that meeting.
The OpenAPI TDC, Travel SIG, as well as the API specification public office hours will be repeating next week. There will also be an AsyncAPI SIG meeting on August 3rd— you can join in via the calendar or sign up to the mailing list on the home page of the AsyncAPI website. I am pushing to get the OpenAPI SIGs more visible in coming weeks to help with onboarding of new users. Additionally you can get in on the ground floor of upcoming potential meetings within the JSON Schema community for their JSON Schema interface description language vocabulary, and chime in on whether or not they should we have a regular call like OpenAPI TSC? #23. Providing some significant opportunities to help define the future of the fast growing JSON Schema specification.
I like to dive into the issues fore each of the specs to understand what folks are asking for and encountering when using the specs. I found the Include JSend in OpenAPI Spec #2664, Ability to provide message when specifying pattern for a query parameter in OpenAPI YAML files #2662, and Usage of field vs property #2660 to be compelling in the OpenAPI community. Over in the AsyncAPI universe I found Address perspective and channel reuse issues through introducing optional 'endpoint' concept #599, Support JSON Schema Draft 2020-12 #596, should binding specs be tied to specific versions of the AsyncAPI spec? #590 and Ambiguity in Operation.message field #588 to be worth taking a look at. I find the issues to be a quick way to get a feel for what is top of mind within each community, but also entertaining to see what the “drive bys” are thinking about.
When it comes to discussions going on within the communities there are multiple places you can tune into what is happening. In the OpenAPI community I recommend checking in on the Overlays discussion going on, as well as the evolving security discussion looking to move forward how keys, tokens, and the other nuts and bolts of authentication operate. Over in the AsyncAPI realm I recommend throwing in your thoughts for their proposal for this years AsyncAPI event(s), tune into the compelling discussions they are having with Thinking Out Loud, and continuing the discussion with Nordic APIs: Leveraging AsyncAPI. Mentioned above, but worth pointing to again as part of discussions, I recommend chiming in on the JSON Schema interface description language vocabulary, and Should we have a regular call like OpenAPI TSC? #23, to help lay the groundwork for the JSON Schema community.
Latest Blog Posts
There were two blog posts coming out of the OpenAPI community. One showcases APIAddicts Joining the OpenAPI Initiative, and the other is the OAI Additional Leadership Job Posting, helping bring in more leadership into the community. I heard through the grapevine that a blog is being stood up for the JSOn Schema community, but I think we will have to wait for another week or so before we’ll see the first post. Remember, you can also submit stories for both OpenAPI and AsyncAPI, and I am sure that if you started a discussion or submitted an issue in the JSON Schema community you could also suggest a blog post for the new blog, helping increase the storytelling going on in any of the communities.
It seems like a pretty slow summer time vibe on the Twitter accounts for the API specifications, and while there was general activity, I already covered most of the items being tweeted out, but there was one from the OpenAPI Twitter account that I thought was worth highlighting.
There were two interesting videos from the last week that I thought were worth showcasing--full disclosure, one of them was my own Breaking Changes show where I talked with Tanya over at eBay.
#ThinkingOutLoud with @dalelane:— AsyncAPI Initiative (@AsyncAPISpec) July 26, 2021
"I've got this stream of events. There might be other developers in my organization that could make other uses of it so I want them to know that this topic is there [...] but I wouldn't consider them to be interacting with my application" pic.twitter.com/0WnV1yhWyv
I've been working on a lit-element based web component for generating forms from a json schema 😃https://t.co/j9wVPqbv68. It's still under construction, that's why I don't have any documentation yet😆but you can see some examples in the demo folder.— Golfo Vasiliou (@faysvas) July 30, 2021
This was my first attempt at doing this type of summary. I will also be posting a little about the process I am using to make this post happen. I will be looking to evolve my approach, and of course, if there is anything missing from my summary of what is going on in the world of API specifications, please let me know! As part of this process I am working to get folks behind the meetings, discussions, and other goings on to be more public about what they are doing so I have a URL to share. Once I get a hang of regular updates for these three specs I will consider adding GraphQL and gRPC. I will be publishing this to the API Evangelist each week (time allowing), and featuring the latest one on the home page. I am also working on updating the home page of the API Specification Toolboxa> to showcase how you can learn, implement, and contribute to each of the specifications—-once I have up, I will link to more from this regularly summary. My goal is to provide a single place everyone can go to get involved within the communities for each of the API specifications, but also stay up to speed on what is going on each week.