We're sorry but this page doesn't work properly without JavaScript enabled. Please enable it to continue.
Feedback

Leveraging documentation power for better web APIs

Formal Metadata

Title
Leveraging documentation power for better web APIs
Title of Series
Part Number
73
Number of Parts
169
Author
License
CC Attribution - NonCommercial - ShareAlike 3.0 Unported:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this
Identifiers
Publisher
Release Date
Language

Content Metadata

Subject Area
Genre
Abstract
Rudy Sicard - 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.