PyCon PL 2014 executable api

Embed Size (px)

Text of PyCon PL 2014 executable api

  • Good API documentation is

    executableWojtek Erbetowski

    @erbetowski

  • Im a programmer

  • Community activist

  • Head of Engineering at Polidea

  • Polidea is all about mobile

  • What is this presentation about?

    A little bit about why

    A little bit about why not

    More about how

  • Do you document your API?

    How many do not document?

    How many document on paper/wiki?

  • none/specs

    WikiOther

    How is your API documented?

  • Do you do WIKI?

    unhappy

    happy

  • Do you do WIKI?

    consumers

    providers

  • Simple and easy

    Easy to create/change

    Easy to modify by nontechnical

  • Not accurate!

    Easily gets out of sync

    You never know whether its you or them

    Not strict

    Often inconsistent

  • How to do it better?

  • What if ...

    you had plenty of time and money?

  • Facebook Graph API

  • DYI solutions

  • Wheres the value?

    Easier to keep up-to-date

    Versioning

    Non-developers may read and maintain

  • Not only for big players!

    RAML

    Swagger

    Apiary

    I/O Docs

    Apigee

    ...

  • Most popular tool

    Apiary

    Swagger

    RAML

  • Give a man an API, and he APIs for a day. Teach a man to API, and he APIs for a lifetime.

    Swagger

  • RAML

    API first

    Readability

    Mocking service

  • An API Is Only As Good As Its Documentation

    Apiary

  • Comparison

    Swagger RAML Apiary

    Executable x x x

    API Platform x x

    Great UI x x

    Readability x x

    Easily generated x

    Scenarios x

  • Future?

  • Summary

  • Your docs can be better!

    Get the best of two worlds:

    easy to keep up-to-date

    simple to create/edit

  • Start with Swagger

    simplest in configuration

    generates docs from current code

  • Big decision

    Generated vs design first

  • QUOTES

  • I could generate docs from existing app

    about Swagger and Jersey

  • It fails during functional tests before we see it

    about mocs generated from documentation

  • Its very hard to return {}but how about null ?

    how technology stack affects API design

  • Q&A

  • Thank you