After prescribing that my clients fire up a GitHub repository and begin centrally managing schema used across their OpenAPI definitions, I want to work on my guidance for helping them bundle and unbundle your APIs. As I sit down to assess the current state I am pleased to see my favorite people have already done great work. Phil has Popular OpenAPI Bundling Tools Compared, and Lorna has a good one on Combine OpenAPI Files–added bonus Unbundle that giant OpenAPI file! from Matt Dodson. I love it when good work already exists, and I am happy to build on top of, and reference in my own work.
So, TL;DR…Redocly CLI is the most advanced solution out there, with [JSON Schema $ref Parse https://apitools.dev/json-schema-ref-parser/docs/] still in the running too. I am doing this work to standardize how I use GitHub to manage OpenAPI specifications, but also JSON Schema artifacts, so I want be thinking about how JSON Schema bundling and management works. As part of this thinking I want to make sure I’m informed regarding overall $ref managementhttps://bump.sh/blog/openapi-asyncapi-ref-usage-guide, and be mindful of the scope of the $ref rabbit hole. I also want to be learning from existing API producers who manage their OpenAPI on GitHub how they are managing, building, but specifically bundling and unbundling their OpenAPIs—I am looking to think more deeply about when you want to do this–even possibly at the runtime?
I have done a lot thinking about and playing around with the modular management of APIs via Git over the last year, and having conversations with folks who are building next generation solutions for helping you manage all your API lego bricks and apply them in next generation interpretations of what an OpenAPI editor is. What I am keen on doing, is continuing to push folks towards managing their inventory of digital resources and capabilities (operations, events, etc.) and their consumption via HTTP - with the API technical contract (OpenAPI and AsyncAPI), and API business contract (APIs.json) provide a nice wrapper for the wholesale and retail distribution of their digital resources and capabilities which are defined and validated as JSON Schema all along the way. I am interested in defining the supply chain of digital resources and capabilities (Lego Bricks), and delivering APIs.json blueprints (Lego Kits) that help people quickly deliver new digital resources in consistent ways.
There is a lot to unpack in this post. I’ll have to play around with Redocly CLI more and use it as part of my APIs.io profiling work. I also have a base blueprint for managing OpenAPI via GitHub, as well as JSON Schema via GitHub, which may be the same thing, or two separate things—depending on your plan of attack. I am just looking for when and where we should be bundling and unbundling via Git repos. I want patterns and anti-patterns for when you bundle or unbundle during design, developer, and now even baked into the runtime. If you know of any interesting approaches, tools, or stories, I’d love to learn more. I am starting with the basics when it comes to my services and guidance for setting up managing OpenAPI and JSON Schema via GitHub repositories, focusing on the fundamentals, but over time iterate upon my approach to OpenAPI and JSON Schema bundling and bundling Kung Fu.
