$30 off During Our Annual Pro Sale. View Details »

API Documentation

API Documentation

Inline Documentation for RESTful web APIs
apiDoc introduction with a small example.
http://apidocjs.com

Peter Rottmann

June 08, 2013
Tweet

Other Decks in Programming

Transcript

  1. APIDOC
    Inline Documentation for RESTful web APIs
    Introduction with a small example.
    http://apidocjs.com

    View Slide

  2. What does apiDoc ?
    apiDoc
    … creates a Documentation HTML-Page
    … use API-Descriptions from your source code
    For who ?
    apiDoc can be used with any programming language, that allow
    block documentation:
    /**
    * This is a comment.
    */

    View Slide

  3. Where i find apiDoc ?
    apiDoc is Open Source and distributed over NPM and github
    Visit: http://apidocjs.com
    Special functions
    apiDoc
    … support own created Templates
    … includes History
    … compare old and new API-Method Versions
    … allows frontend Developer to see what changed
    … support Inherit
    … reuse of Documentation parts
    … extendable
    … you can create your own Documentation Methods

    View Slide

  4. Ok, let us begin...
    apiDoc is a node module, so install Node.js first:
    http://nodejs.org
    Node.js includes „npm“, a package manager for node.
    Install apiDoc
    [sudo] npm install -g apidoc
    We install apiDoc global, so you can access it from everywhere.

    View Slide

  5. EXAMPLE PROJECT
    We use a simple static JavaScript example.
    We ignore routing, validation or database operations.
    This are only small parts of apiDocs functions, for all visit http://apidocjs.com
    There is also a complex example: http://apidocjs.com/#example-full

    View Slide

  6. Create a new directory „my_project“.
    Within that dir create a file „example.js“.
    example.js
    var currentUser = {
    name: 'Mary'
    };
    function getUser() {
    return { code: 200, data: currentUser };
    }
    function setName(name) {
    if(name.length === 0) {
    return { code: 404, message: 'NameEmptyError' };
    }
    currentUser.name = name;
    return { code: 204 };
    }

    View Slide

  7. A basic doc
    Above „function getUser“ we place a basic documentation block
    /**
    * @api {get} /user Request User information
    * @apiName GetUser
    * @apiGroup User
    */
    function getUser() {
    return { code: 200, data: currentUser };
    }
    This 3 parameters are required!
    @api describes the path of the Method that clients call.
    @apiName is a unique Name, you can name as you want, for simplicity i prefer
    „Type of Method“ + „Name of Method“ e.g. {get} and „/user“ => GetUser.
    @apiGroup is the name of the group to which this method belongs. The group will be
    used for Navigation.

    View Slide

  8. By default apiDoc search for all „.jjs“ files in current directory and sub directories.
    You can change the includeFilter, call „apidoc -h“ for details.
    apiDoc created a new HTML-Page in directory „doc“.
    From command line run within „my_project“ directory:
    apidoc

    View Slide

  9. Open „doc/index.html“ in your Browser
    We see the rudimentary Webpage, with Navigation left and Content right.
    We have a group „User“ and within that group an API-Method „GET /user“

    View Slide

  10. Describe the API-Answer
    Now we add success return parameters
    /**
    * @api {get} /user Request User information
    * @apiName GetUser
    * @apiGroup User
    *
    * @apiSuccess {String} name The users name.
    */
    function getUser() {
    return { code: 200, data: currentUser };
    }
    apidoc
    Run apiDoc again, it will overwrite the „doc“ Directory

    View Slide

  11. Now we have a little more Information and see what „GET /user“ returns on a
    successful reply „Success 200“.

    View Slide

  12. Add a Version and example Code
    We add a Version (Format “major.minor.patch”, see http://semver.org for details)
    and we add an example code, that shows what will be return in case of success
    /**
    * @api {get} /user Request User information
    * @apiName GetUser
    * @apiGroup User
    * @apiVersion 0.1.0
    *
    * @apiSuccess {String} name The users name.
    *
    * @apiSuccessExample Example data on success:
    * {
    * name: 'Paul'
    * }
    */
    function getUser() {
    return { code: 200, data: currentUser };
    }

    View Slide

  13. In the right dropdown box we see now the Version „0.1.0“ and under „Success 200“
    our integrated example.

    View Slide

  14. VERSIONING
    If you work in a Team and some Programmer work an the API backend and some on
    Frontend Client, it is important to know what changed in a new Release.
    Especially during developing an Application, many things can change.

    View Slide

  15. An API Method change
    Create a new file „_apidoc.js“.
    Put only the documentation Block from „getUser“ in that file:
    _apidoc.js
    /**
    * @api {get} /user Request User information
    * @apiName GetUser
    * @apiGroup User
    * @apiVersion 0.1.0
    *
    * @apiSuccess {String} name The users name.
    *
    * @apiSuccessExample Example data on success:
    * {
    * name: 'Paul'
    * }
    */
    „_apidoc.js“ will be our history file and contains old documentation blocks.

    View Slide

  16. Now we change the documentation block in „example.js“
    example.js
    /**
    * @api {get} /user Request User information
    * @apiName GetUser
    * @apiGroup User
    * @apiVersion 0.2.0
    *
    * @apiSuccess {String} name The users name.
    * @apiSuccess {Number} age Calculated age from Birthday
    *
    * @apiSuccessExample Example data on success:
    * {
    * name: 'Paul',
    * age: 27
    * }
    */
    function getUser() {
    return { code: 200, data: currentUser };
    }

    View Slide

  17. After call „apidoc“ and open „doc/index.html“ you see now Version „0.2.0“ with the
    Field „age“ and the changed example.

    View Slide

  18. And now the magic...

    View Slide

  19. Select from Dropdown „0.2.0“ the Version „0.1.0“.
    You see now a comparison from the 2 Versions. Green marked content indicates the
    Fields that are added to Version „0.2.0“.

    View Slide

  20. In the future, when you made more changes to an API-Method, simply copy and add
    the complete documentation block to the history file „_apidoc.js“.
    Leave the old blocks as they are.
    Then you have a Documentation where everybody can see any change of your API.

    View Slide

  21. PARAMS AND ERRORS
    We take now a quick look at how to add Parameters, that an API-Method need and
    how we return errors.

    View Slide

  22. We add now a documentation to our second function „setName“.
    example.js
    /**
    * @api {put} /user Change User
    * @apiName PutUser
    * @apiGroup User
    * @apiVersion 0.1.0
    *
    * @apiParam {String} name New name of the user
    *
    * @apiError NameEmptyError The name was empty. Minimum of 1 character is required.
    */
    function setName(name) {
    if(name.length === 0) {
    return { code: 404, message: 'NameEmptyError' };
    }
    currentUser.name = name;
    return { code: 204 };
    }

    View Slide

  23. You will see now the new „Change User“ entry in navigation and the content for the
    API-Method.

    View Slide

  24. Thank you and have a productive use !
    For more Information visit http://apidocjs.com
    Author: Peter Rottmann
    [email protected]

    View Slide