Leveraging documentation power for better web APIs

‘Rich’ web APIs that are easier to understand, develop, test and use, is a popular subject. There are a lot of new specification languages (e.g. swagger, apiblueprint …) and libraries (django-rest-framework, drf …) that provide features in this direction. Following the old proverb “An API is only as good as its documentation”, we decided to play with these ideas and focus on leveraging the power of documentation. We propose to use the code documentation and the type system to provide: - browsable APIs, that are easy to interact with and visualize, reducing the need to provide custom UIs - verification of inputs/outputs along with precise error message if needed - automatic [de]-serialization of inputs/ouputs outside of the domain code - smart exception handling, e.g. exceptions that are not documented are automatically converted into internal errors - automatic testing, e.g. input, output and result including exceptions are tested ensuring the code works and the documentation is up-to-date.

This use case is one of the rare situation where introspection is desirable and unavoidable. And Python is a good language to explore/exploit code and documentation dynamically. The perfect excuse to spend some time on meta coding a first implementation while being at work. We’ll demonstrate what we came up to, the advantages and limitations compared to other approaches. And we’ll share the lessons we learned from this experiment.