======
Ariane
======

Ariane is a python package for describing, producing and visualizing RESTful APIs.
It can help you create a Rest Api object that you can use with any template engine in python (Django, Jinja2).
Or you can create an automatic documentation and use the templates provided by the community and automate the generation of the documentation for your API.

    #!/usr/bin/env python

    from ariane import ariane

    restApiDoc = ariane.RestAPIDoc('api_description.txt')
    restApiDoc.generate('documentation.html', 'templates/template.html')


Installation
============

    Ariane is a python package. You can install it with pip:
    pip install ariane

more information: https://pypi.python.org/pypi/Ariane

Overview
=========

your api_description.txt looks like this and use ConfigParser file format


[api]
name = Ariane Api Description
version = 1.0.0
base_url = http://localhost:9999/api/

[code_status]
400 = Bad input parameter. Error message should indicate which one and why.
401 = Bad or expired token. This can happen if the user or Ariane revoked or expired an access token. To fix, you should re-authenticate the user.
403 = Bad OAuth request (wrong consumer key, bad nonce, expired timestamp...). Unfortunately, re-authenticating the user won't help here.
404 = File or folder not found at the specified path.
405 = Request method not expected (generally should be GET or POST).
503 = Your app is making too many requests and is being rate limited. 503s can trigger on a per-app or per-user basis.
5xx = Server error.

[auth:GET]
url = /auth/logout/
description = clear an existing cookie in the session
input =
return =

[auth:POST]
url = /auth/login/
description = create a cookie in the session
input :
    {
        "username": "",
        "password": ""
    }
return :
    HTTP/1.1 200 OK
    Content-Length: 0
    Content-Type: text/html; charset=UTF-8
    Server: TornadoServer/2.4.1
    Set-Cookie: user="ImFkbUluIg==|9364473586|0ef6536217a330f6574831ed672666ca0eaaeab4"; expires=Sat, 27 Apr 2013 12:26:27 GMT; Path=/

Tutorial
========

1. create your api description file
All information in this file is saved in sections. A section is shown with brackets
    [section]

There are two mandatory sections. If you do not want to use, you can simply remove the fields in the section:
    [api]
    #nothing here

    [code_status]
    #nothing here

All resources are describe is section too. You must add the HTML verbs after two points in section
    [resource:HTML_VERB]
example:
    [dog:POST]
describe the POST method on dog resource
you can add all the information you want under resources section:

    [dog:POST]
    url = /dog/
    description = create a dog
    input :
        {
            "name": "",
            "birthdate": ""
        }
    return :
        HTTP/1.1 201 CREATED
    custom_field = Custom field

All information on several lines (eg input parameters) must be preceded by a colon (:) and indented
Good
    input :
        {
            "name": "",
            "birthdate": ""
        }
Bad
    input =
    {
        "name": "",
        "birthdate": ""
    }

2. Get all the information about resources in RestAPIDoc object:

    from ariane import ariane
    restApiDoc = ariane.RestAPIDoc('api_description_file')
    print restApiDoc.resources[0]["type"]
    >> POST
    print restApiDoc.resources[0]["custom_field"]
    >> Custom field


3. handle errors
    from ariane import ariane
    restApiDoc = ariane.RestAPIDoc('api_description_file')
    if not restApiDoc.is_valid():
        print restApiDoc.error_message

4. all the fields available in RestAPIDoc object are:
['api', 'code_status', 'error_message', 'is_valid', 'resources']


History
=========

Ariane is the french translation for Ariadne
Ariadne in Greek mythology, was the daughter of Minos king of Crete. She is mostly associated with mazes and labyrinths, due to her involvement in the myths of the Minotaur and Theseus.
"Un fil d'Ariane" (Ariadne's String) is a french common name for a distance line, penetration line or guideline used by SCUBA divers.
Ariadne's String is a string that helps guide someone through the Labyrinth of the Minotaur.

Python Ariane package helps to understand your API, and helps you to offer a good documentation for your Restful API.


License
=========
Ariane's License is the WTFPL – Do What the Fuck You Want to Public License.

        DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. You just DO WHAT THE FUCK YOU WANT TO.



