Rudy Sicard - Leveraging documentation power for better web APIs
Channel: EuroPython Conference
Date: 04/08/2016

Rudy Sicard - Leveraging documentation power for better web APIs
[EuroPython 2016]
[21 July 2016]
[Bilbao, Euskadi, Spain]
(https://ep2016.europython.eu//conference/talks/leveraging-documentation-power-for-better-web-apis)

Web APIs that are easier to understand, develop, test and use, is a
popular subject. "An API is only as good as its documentation". We
decided to play with this proverb and leverage the power of
documentation. We propose to use the code documentation and the type
system to provide lots of free features: explorable APIs, better error
messages, automatic testing.

Python is perfect to explore code and documentation dynamically. We'll
demonstrate what we came up to and the lessons we've learned.

-----

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