We’ve been chugging along defining the API endpoints. The file linked below is last week’s efforts, though it rests in an incomplete state; we’ve come to the limits of comfortably defining things like JSON responses and HTTP methods within Excel. You can count on the endpoints, HTTP methods, and meanings themselves being well set at this point — where the ambiguity lies is with the deeper information around requests, responses, and content.
To that end we’re now starting our next step of codifying the API: using something other than a traditional text document, as we discussed in our state of the union a few weeks back. We’ll be using a domain-specific language: the OpenAPI specification. While text works very well for explaining the why of something, it quickly gets difficult to manage when explaining the how once you get into minutiae.
Why OpenAPI? A few key implementers let us know that they are driving their development efforts using Swagger.io, the owners of which seem to be one of the main drivers of the OpenAPI specification (if not the primary driver). I was initially a little hesitant to make Swagger part of the core deliverables of our project, because I don’t want to get locked into a proprietary PaaS solution, but with the availability of the latest OpenAPI spec, there are now full and well-formed methods of communicating and working without using Swagger.io’s value-add ecosystem.
In particular Swagger develops an offline HTML tool, Swagger Editor, that can import and export specs in both Swagger.io and OpenAPI formats, as a convenient YAML file. On our call tomorrow, I plan to ask for feedback on how much of the Swagger-controlled infrastructure is appropriate to take on. There’s also an unknown cost to having Swagger host the final spec that we’ll have to figure out. Since we have our own server and domain, self-hosting may be the best option, but there are some important unknowns.
Regardless of hosting a “living” API reference, I anticipate we will release a YAML file to serve as the full canonical Sandpiper API specification alongside our schemas (SQLite and XSD) and the framework model document. Because YAML is text-based it can also become part of a source control system, which will be important once we reboot the Sandpiper Github repository (speaking of PaaS and mitigating this with offline and peer-to-peer tooling, Git is a good example).
In other news, the Teams link for the last round of technical meetings is now expiring. Our next calls are, as before, open to any interested developers, via this new link. The meeting is every Friday at 11:00am US Pacific Time / 1:00pm Central / 2:00pm Eastern / 6:00pm GMT (during the summer). Hope to see you there!