Documentation-driven development for APIs | Hacker News Reader

Documentation-driven development for APIs

medium.com

33 pointsabunuwas14 comments

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. 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...

> 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.

It 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 to that, but the API still had to be coded by hand to comply with the spec.

A way to feed the oas.yaml code to flask-smorest somehow so it derives the endpoints and schemas from that (hey it already makes a ton of assumptions about how to structure the application, requiring e.g. a set of methods named exactly as the endpoints so they can be easily matched) would make it so the single oas.yaml file drives both ends of the implementation, would make coding work easier as the schema doesn't need to be described multiple times in multiple languages/formats, and would provide quick feedback (FAILURES) if I change the schema without coding the required endpoint support.

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").

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.

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!

[0] https://github.com/quicktype/quicktype

Perhaps "Specification-Driven Development" would be a better descriptor.

A lot (although not all) of the advantages of the method given here are also advantages conferred by something strongly-typed like ASP.NET; quite a bit of the testing in the post seems to be there solely to make up for the fact that you can't specify the type of your output up front.

IMO something like Apiary [1] and running the blueprint as a mock server is even easier.

[1] https://apiary.io/how-apiary-works

Apiary looks like it supports OpenAPI 3.0, so you get the best of both worlds. Having your API spec living in an open standard format also gives you the ability to easily write integration tests using other tools as well.

At first I thought this might be doc-tests-for-REST.

Kinda disappointed. Doctests are nice. You should be able to doctest REST APIs.

Tools like Postman make it really easy to write test scripts and automate other things around endpoints that are defined using OpenAPI, so you're pretty close once you have the OpenAPI spec written.

Fair, but it seems to be kind of an overkill for simple APIs, specially when it's internal APIs developed by a team that works well together.

I recently joined a company that builds all of its APIs this way, and I'm not looking back. It's so much easier to communicate across teams and tech stacks when we can send them a PR with a proposed endpoint contract. Plus, people always come and go and good API docs can help a new developer ramp up considerably faster.

Reply on news.ycombinator.com