gistfile1.txt

// Example of HTTP API documentation format based on Apiary blueprint

== transport | Transport system

Markdown description of an entity goes here.


    == transport/cards | Customers' cards

    @keyword [string] Keyword of a card
    @number [string] Number number where you are I will catch you for the bra

    Entity has attributes description and also free form markdown.

    Thanks to the fact it uses `foo/bar` notation as the keyword it can be split into several 
    files and parsed in any order. Those keywords can also be automaticaly picked up as parts of
    requests' urls.

    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    >> GET
    
    This request is supposed to mean `GET /transport/cards`. Each entity can have any number of
    requests.

    Examples are no more a separate entity. They are just a specific highlight for the markdown
    code block.

    ```http
    > Accept: application/json
    < 200
    < Content-Type: application/json
    {"cards":
      [
        {
          "expirationAt":"2013-04-15",
          "accountNumber":"1",
          "cardTypeKeyword":"visa",
          "fk":"123",
          "image":{
            "image":{
              "url":"/uploads/card/image/1/1.png"
            }
          },
          "issueAt":"2013-01-14",
          "number":"12345",
          "productFk":null,
          "productType":null,
          "state":"active",
          "title":null,
          "userFk":"test_user_1"
        }
      ]
    }
    ```

    << POST /cards/ololo

    This notation describes a callback. You can use this block to describe it's logic.

    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    >> PUT bar

    This notation will build /transport/cards/bar url. Use `/bar` to skip namespace.

    ```http
    > Accept: application/json
    < 200
    < Content-Type: application/json
    {
      account: 1,
      number: "1234",
      card_type: "visa",
      issue_at: "01-01-2013"
      fk: "1"
    }
    ```


    == transport/accounts | Account transport

    Another description. So much fun!

    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    >> GET http://www.google.com

    Sometimes you might want to inject complete URI. You are welcome to.

    ```http
    < 200
    < Content-Type: application/json
    {"accounts":
      [
        {
          "committedBalance":"37859.92",
          "currencyIsoCode":"rur",
          "minimalBalance":"0.0",
          "number":"1",
          "pendingBalance":"0.0",
          "productFk":null,
          "productType":null,
          "title":null,
          "userFk":"test_user_1"
        }
      ]
    }
    ```    

Boris, I am pleased with your interest. Please get back in touch should you be interested in discussing new API Blueprint Format.

Thank you.