Leveraging documentation power for better web APIs

Video thumbnail (Frame 0) Video thumbnail (Frame 1214) Video thumbnail (Frame 2057) Video thumbnail (Frame 2842) Video thumbnail (Frame 3480) Video thumbnail (Frame 4157) Video thumbnail (Frame 5788) Video thumbnail (Frame 7318) Video thumbnail (Frame 8048) Video thumbnail (Frame 8724) Video thumbnail (Frame 9251) Video thumbnail (Frame 11801) Video thumbnail (Frame 12789) Video thumbnail (Frame 14032) Video thumbnail (Frame 15556) Video thumbnail (Frame 17430) Video thumbnail (Frame 18431) Video thumbnail (Frame 20009) Video thumbnail (Frame 23361) Video thumbnail (Frame 23824) Video thumbnail (Frame 24374) Video thumbnail (Frame 25296) Video thumbnail (Frame 25951) Video thumbnail (Frame 27160) Video thumbnail (Frame 28129) Video thumbnail (Frame 28780) Video thumbnail (Frame 32297) Video thumbnail (Frame 32992) Video thumbnail (Frame 33774)
Video in TIB AV-Portal: Leveraging documentation power for better web APIs

Formal Metadata

Leveraging documentation power for better web APIs
Title of Series
Part Number
Number of Parts
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 license.
Release Date

Content Metadata

Subject Area
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.
Revision control Context awareness Demon Scaling (geometry) Absolute value Power (physics) Power (physics) World Wide Web Consortium
Context awareness Presentation of a group Computer animation Software Different (Kate Ryan album)
Computer animation Moment (mathematics) Software framework Exploit (computer security) Web browser
Point (geometry) Latent heat Computer animation Design by contract Interface (computing) Design by contract Parameter (computer programming)
Computer animation Validity (statistics) output Instance (computer science) Bounded variation
Metropolitan area network Dependent and independent variables Computer animation Finite difference Operator (mathematics) Phase transition output Family Form (programming) Chi-squared distribution Annulus (mathematics)
Focus (optics) Computer animation Validity (statistics) Code Function (mathematics) String (computer science) Operator (mathematics) output Convex hull Data conversion Right angle Chi-squared distribution
Computer animation Validity (statistics) Multiplication sign 3 (number) output Parameter (computer programming) Client (computing) Table (information) Form (programming) Form (programming)
Implementation Service (economics) Computer animation Agreeableness Design by contract Statistical hypothesis testing Statistical hypothesis testing
Addition Computer animation Regular graph Open set
Point (geometry) Functional (mathematics) State of matter Multiplication sign Causality Cuboid output Error message Exception handling Default (computer science) Parsing Information Mapping Consistency Interior (topology) Statistical hypothesis testing Electronic signature Type theory Computer animation Agreeableness Function (mathematics) output Data conversion Exception handling Form (programming) Window
Parsing Game controller Constraint (mathematics) Constraint (mathematics) Interior (topology) Electronic mailing list Parameter (computer programming) Arithmetic mean Type theory Computer animation Function (mathematics) output Data conversion Object (grammar) output Exception handling Data type
Boolean algebra Service (economics) File format Interior (topology) Subset Performance appraisal Type theory Number Computer animation String (computer science) Object (grammar) output Right angle Data structure Data conversion Object (grammar) Integer Glass float
Group action Functional (mathematics) Boolean algebra Constraint (mathematics) Weight Tape drive Data dictionary Object (grammar) Data structure Data conversion Implementation Social class Exception handling Form (programming) Data type Addition Rational number Validity (statistics) Consistency Interior (topology) Code Parameter (computer programming) Type theory Number Computer animation Personal digital assistant String (computer science) Function (mathematics) Thermal radiation output Data conversion Integer Glass float Exception handling Library (computing)
Default (computer science) Functional (mathematics) Scripting language Java applet Content (media) Design by contract Parameter (computer programming) Distance Event horizon System call Template (C++) Medical imaging Type theory Computer animation Personal digital assistant Operator (mathematics) Summierbarkeit Text editor Curvature Form (programming) Resultant Exception handling Wide area network
Randomization System call Addition Line (geometry) Instance (computer science) Distance Statistical hypothesis testing Mathematics Strategy game Operator (mathematics) output Category of being Form (programming) Exception handling Data type Area Theory of relativity Electric generator Computer file Content (media) Hypothesis Type theory Message passing Word Error message Computer animation Personal digital assistant Function (mathematics) Strategy game output Software testing Data conversion Exception handling
Functional (mathematics) Implementation Water vapor Information security Capability Maturity Model
System call Addition Dependent and independent variables Line (geometry) Virtual machine Instance (computer science) Counting Exclusive or CNN Software framework output Website Category of being Data type Dependent and independent variables Link (knot theory) Mapping View (database) Computer file Hypothesis Error message Computer animation Agreeableness Function (mathematics) Strategy game Software framework Software testing Data conversion Exception handling Sinc function
Dependent and independent variables Functional (mathematics) Link (knot theory) Touchscreen View (database) Dependent and independent variables View (database) Decision theory Instance (computer science) Mereology Rule of inference Timestamp Mathematics Computer animation Agreeableness CNN Software framework Utility software Integer output Physical system
Recurrence relation Dependent and independent variables Link (knot theory) Information View (database) Dependent and independent variables File format Parameter (computer programming) Staff (military) Counting Mathematics Computer animation Agreeableness Operator (mathematics) Software framework output Energy level Musical ensemble output Pressure Chi-squared distribution
Web page Link (knot theory) Operator (mathematics) Form (programming)
Code generation Implementation Group action Presentation of a group Source code Design by contract Mass Distance Type theory Software testing Summierbarkeit Library (computing) Metropolitan area network Pairwise comparison Addition Electric generator Shared memory Content (media) Client (computing) Open set Hypothesis Message passing Computer animation Data conversion Task (computing) Library (computing)
Type theory Word Service (economics) Type theory Computer animation Data conversion Task (computing) Statistical hypothesis testing Form (programming)
Revision control
welcome all we have really here showing us how to leverage that revision powers for better ABS June some happened
general so and along with the and what you have to do the company that they develop doesn't need S and then as add that scale my
team is money going to look fall latch software and other inventory and sometimes and sometimes they the this team we
decided to make money doing as a series and stop to experiment different daisies would sell his son was able at for this presentation gives a glimpse of of of what we have done and this is a joint work with my greedy you you global which is there and and some of the people that
of the so what Abruzzo
beloved it yeah what you see is it's composed of 2 the pose of the walls so of it's
182 employers them and more importantly so it's related to exploitation experimentation and I we at the at the moment and there is
a world it tonight uh we got the former don't so finicky i is the gain of contracts it can be very explicit like assured declaring slugger specifications find point can being inclusive that the argumentation uh do contracts defines the values used under
salaries that is going to be it or don't passion again during this really salaries and also so
what other valid inputs for variation in in the seventies so why is it in there is and because it brings the other feature for instance so the 1st feature we developed
this is why we we I the documentation tool describe the PPI then I
will speak about the feature that's traveling brother he had sold the 1st basically feature is the fixed probability it means that you can go to a PI I and ask what the dual Laplace that so we have you have often that and the and that carries different operations and then you can just click on and operation and you see the documentation of that operation Department of phase and 1 of the possible and then more than that you can play with an operation so you have to it's in the input of the old fashion and colleagues and so you can see where that leaves the response explore beauty or the the duration but that being the important like it
just input can be this so we for believe can do something better
and has already embarked on future of Nicaea aim is to reinforce the validation of the input from the from the input and the inputs by the way just don't focus on the edges and importance you'll want an operation to be using the that that that direct that's why you should really dates on the inputs of the if you started like various transmitted instead of strings nobody knows all of the code we would hold the current we BAT in that case and for already Hjerson inputs um you may want 1 of the Convention between this is an important on between your right and then OK this 1 is and the
just feature legacy before it can be really painful to ontologies and that that because it's there was so much in so having forms MIT you times hunts it's brings clients side uh input validation on the table and others are pretty interesting future
that's you have the gain of the contracts when you have your service implementation and as you want to be sure they they've much so that would be really cool to reduce ask for automated tests for taking that the matter now we also
present that was a feature of that makes the president had been more user-friendly the
last but just to mention that you may want to generate even if you use the Dodge more for this additional cost like Macleans regular because regular as a
lot of k in feature that you can make it so and this is the prime
of the time due to convert the time starting at so imagine you want
who had a new function between your that you will again what do you do OK it's easy you document the functions and you out there to be decorative on its soldiers the got time we were as strong as a style the function as in the pageant in GPS the function will be left and unmodified so you can still use it as the default window out at the decoder was that they and and the since the function will be rapidly in the DAPI where on the day that I about the HTTP and when the so is done the according to we Boston that so that's why we have information about the importance of inputs and the exceptions this gives you the data from the State concerned about inputs Both points and possible error and causal the signature of functions give you the full value for inputs so here we have consonants that's what in the red boxes uh their consensus now more than just the names they can be parametrized for the mapping types like here we
have a prime is right least I think that is parametrized by made to be um all can also
contain several name like the 1st parameter its as a means of asserting and from
that constraints we can define or do all on the input should be validated and so slated to conscious and that of structural tools right and objective for that so we call that that that constraint to a some schema control
imposed the people that Poland brain what is just and unjust and formats and this is an object can be seen as a subset of the beating it and that's so often the conversion between the 2 is free have but for your service is used to to do I just you you may need to do additional evaluation and this is done by resistance to so what is your schema resistance tumor uh he described the structure of the expected is just some right it's types or its minimum value when it contains when it
contains they're like the name of the she is the 1 that optional it's 20 describes what expecting as a new input and there was
situation where you want we rations append so you have like Jason dictionary and you wanted to be equal relative to you all latent class so for these 2 when you want to have additional radiation and Kristen Grauman action we introduced 2 classes that tapes to attach the question on on schema to your idea consists so from that's the way I voted to retreive Richerson schema from any their consonants so what does
the validation the conversion but when the uh the Saracens on the input received as a 1st validation form was visited validation relies on that their concerns and commendation fall more in next 1 we realized when these Jasinski so there's a library ecologist and schema that you can use to regulate Indian near the structure with you just have to and after that validation there is the Convention mentions that that is why there in peace seats for the most basic type all constructed using the form just in the cases and then there are a function is called and from that there can be what comes you haven't exceptions and so what we do is that we check that the exceptions is the
respecting the contract she it's not uh at the contents of the exception that event because we don't want the user or the seventies to see initiated is not accepted by contract and at last before we get the results from the function call we ready data the there is a need what else can we do with his sons came up it's a sum so you can use just
disseminated our it's able to use the resistance can mount to generate a which is what's going develop it's a to validate the form and give you back the very they and so you just have to the reading a good tool decimated on your it's images from from plates and the other could feature for almost nothing so the idea of a review of what you write default you have to type the distance content in the play with the text around and using doesn't uh it is only just over from so it's really is to to creating inputs and that that down the destiny of future Morris from operators should the causal In this case the caffeine when you need that this
area is therefore the form just like so you have to write it into some form to so
what else can we do with just came up I don't know if you know all
the package name you put this this uh um the of cage that they're you to do a proxy-based they seem some so it's composed of strategies that are able to word generates a random inputs for many years the usual types on array of enticing to rely own quite due to use of the so let's add the generation shouldn't strategy for distance we that's how we can generate this relation that on the operation of all salaries respect this quantifying the quantized described by the documentation so here have proved to examine sold have taken the the ready to quantify that respect the content of the EPA of modified its so in the 1st case uh hi changes occurred just before it was always in an exceptionally high energy that the paper or like at higher the instances and from there with magic tests we have message age well the type always discovered that he shown to about that we propose that Tracy and Cervantes do the analyzes so 1 that 1 of the exceptions that is described in the compact he's never no cultural way this operation so it shows that to what is described in the documentation could be automated conference and
then after that the news example while I'm we defined the value garden which but value you think restructuring for a function that is is expected to work on consumption that's and so
what we see is that its costs will be detected that the maturity so uh where something that's there is a birds who textual water it yeah and that the security check that what's you are describing the documentation is on par with the chant implementation
which is really good turn so
what can I do exclusion since map I don't always stupid but there so we origin of an easy way to want just some the reforms and can we have some machine use of on to the Israelis he's utilize there's some response and so taking inspiration from John framework that already does the crowing of disease and response we decided to
rule uh and uh to add something that we call the pretty you so a pretty view it helps you to define focused on his utilization of the disease and response so here for instance so you have do overview you the ball pretty you and they're all part of the screen
and you can see that the urges and containment timestamp hence individually things functions score the actually you manually David and on this so another example where you have an integer value in decisions and wanted as posterior semantic and of the but it's usually is able to ensure that semantic we find that the values 0 which is of critical give like so it it's crazy to make their own the system response the 0 to read for all human and
staff and and of things that we added to the to the pretty is the and EDT to add extra information that the other party you say something about active bands that are not and the challenges of response and although he and yeah that's expand formation and that change which required input and it's a gene that is able to which 1 is operation on pressures on the information in the
form of so you can navigate between different feature in the the API and you don't have to to do to binging so there when you click
on the red link you go to the operation page to some of the and solve Russian based on their if really are in the region so what's next
we plants who open source the on the things that we present so you
can watch this action and already uh we really had no the different contribution there you we Rios us all contribute to it with this this with the adjacent to mass with it 1 thing that we we didn't do want the during testing needs to support in them that you because it's really comparison in that place the and to interact more always the because the addition that I showed you that gives you like a jingoistic for you on your the man with the warning and all about this much between the contract and the implementation of currently you have to work and it's by an I would be the title you know there invigorated the standoff distance and linkage then there is this way Gasping generation so we already have a lot of could fit so why do we want that because it's so as the DAG to generate good claimants could library that means you good that you are serious and by 10 and then you want people to of automatic access and use right this we're fine and between generates the clan for you and but it's really good things so the share of 2 the qualitative a simple message from this presentation was able I be down where In the 1st instance because they're very user friendly wants that you can the content and fixed
granted from the documentation and the types the thinking you are used to and the other feature to your services so the idea that some exemplary the future of on but there's a lot more things to do and hence protocolized
provisions discernment down very since there are still not there at the end of 2 words around then so for this to to use them I think the between you is the new features in your presence and that's on the you of questions
FIL if versions thank you for coming