Ask HN: How do you make sure a back end matches API-spec?

4 pointsdachrillz3y ago2 comments

Hello everyone,

I've sort of come to the conclusion that I prefer writing API-specification (Open API in this case) before starting to write the application itself.

The reason mainly being that if one writes the specification first, one has to think through the api, its error codes an so forth. There is nothing wrong with going the other way, namely generating the specification from the code. However, I have this intuition that there will always be edge cases where you will end up having to manually write parts of the specification anyways.

This means that there is a great risk that the specification drifts from the implementation as the application/specification matures. The reason being is that one has to manually make sure that the specification matches the application, which is bound to be error prone!

My question is basically, how would you approach this problem? Do you know any tools that can help one make sure the specification matches the application? I've looked through some of the "Open API tools" [1], but none of them seem to really fully solve the problem.

Thank you for your time :D

[1] https://openapi.tools/

2 comments

yababa_y3y ago

Great question! It fractally occurs at every level of the stack, I dealt with it when formally verifying operating systems, compilers, and runtimes: what do we mean by correct, and how can we assure our implementation has that property? You have the right instinct that it's important to have a specification.

One approach is to use an "executable specification", and now the problem becomes is the specification interpreter/compiler correct? If so, your implementation has no choice but to match the specification. The Python library Connexion implements this approach. https://connexion.readthedocs.io/en/stable/routing.html you augment your spec with specific python functions. It will automatically validate all requests against the spec.

Another approach is template generation, where the specification becomes input to a code generation, forming the skeleton that you fill out with your code. Swagger Codegen uses this approach. There are other generators too. I haven't used them, but I'd be worried about the overhead of regeneration/specification change, and possible implementation drift.

At a different level entirely, you have automated testing. https://dredd.org/en/latest/index.html is a great tool for OpenAPI. It's basic behavioral testing that the implementation matches the spec. If you're using the above approaches, running such a test is kinda superfluous. https://schemathesis.readthedocs.io/en/stable/ is another cool one. If your main worry is specification drift, these tools are your friends.

mdcds3y ago

Several teams at my org use Smithy. The gist of it is that you define the spec and Smithy will generate the data model and clients.

https://awslabs.github.io/smithy/

j / k navigate · click thread line to collapse