Funnily enough, I'm trying this right now with a personal project using JSON Schema and quicktype [0]. It's phenomenal how it's nudged me to really think about the boundaries between components, and I get type-safe serialization code generated for free!
Documentation-driven development for APIs
11–15 of 15 posts
Re: Documentation-driven development for APIs
#12It would be great if the API specification could be written once and then consumed by both server and clients, not only for functional validation as shown in the article but also for the server to use the spec to validate and serialize inputs/outputs. As described, there is a disconnect where you went to all the work to create the openapi oas.yaml file, and can feed that to your test client to ensure the API responds…
CORBA kind of has you do that. You still have to add details for the implementation, but you write an interface description once and then both the client and the server know how to communicate. A code generator will produce that interface code, and can stub out the implementation part.
A lot of middleware systems do things like this. The critical part of what the author is doing is that they're spending time developing a specification. If you just grow it organically, on a larger project you're more likely to end up with a mess than a coherent system.
Re: Documentation-driven development for APIs
#13It would be great if the API specification could be written once and then consumed by both server and clients, not only for functional validation as shown in the article but also for the server to use the spec to validate and serialize inputs/outputs. As described, there is a disconnect where you went to all the work to create the openapi oas.yaml file, and can feed that to your test client to ensure the API responds…
In my opinion, this is one of the weakest points of spec-heavy approaches. These kinds of tools/approaches work great the first time you use them, but end up adding a lot of friction long-term. Or even immediately if that initial spec has to be re-done when requirements change just before implementation ships.
Although having a consolidated OpenAPI spec is miles ahead of plaintext documents in GDrive/DropBox, it feels like we could do so much more by using documentation to directly align and inform systems as they evolve (not just "at rest").
Re: Documentation-driven development for APIs
#14I would say that documentation-driven development is not really documentation-first: when I do it there's a close feedback between implementation and documentation. What will often happen is I'll start writing down the documentation for a prototype and it'll be so full of awkward preconditions or poor ergonomics that I will realise where I need to make improvements.
Regarding this particular example, the API specification is not what I would call documentation since it leaves the reader to guess most of what is going on. A todo service is trivial, but maybe if it had more explanation the author would have spotted the stray 'priority' in the first version of the schema...
Re: Documentation-driven development for APIs
#15I would say that documentation-driven development is not really documentation-first: when I do it there's a close feedback between implementation and documentation. What will often happen is I'll start writing down the documentation for a prototype and it'll be so full of awkward preconditions or poor ergonomics that I will realise where I need to make improvements. Regarding this particular example, the API specific…
> I would say that documentation-driven development is not really documentation-first: when I do it there's a close feedback between implementation and documentation.
I've done it both ways. I've literally written the documentation first (it's the style of doco you read for the standard Python library), and I've designed the API and written the doco afterwards. In either case there is another step: writing the unit tests.
All three steps can have a large effect on the design of the API. You focus on getting the internals working correctly when writing the code - the API is just an interface sitting on top. Unit tests make you focus how easy or otherwise it is to use that API, which turns out to be a very different thing. When when you write the doco, you have to explain how the API should be used to someone else. I can't count the number of times I've produced a working tested API, only to discover when I tried to explain how to use it someone else (ie, write the doco), I've found myself twisted in knots. Rather than push through it's easier to rewrite the API in terms that is easier to explain.
I've not noticed doing the three things any particular order is always more efficient that any of the other orderings. Sometimes one stage triggers a lot of re-work, sometimes it doesn't. I guess that means I'm not smart enough to focus on all three outcomes at one time.