.. Mam Zdanie API documentation master file, created by
   sphinx-quickstart on Tue Mar 20 10:27:02 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Mam Zdanie API's documentation!
==========================================

Welcome To `Mam Zdanie <http://MamZdanie.org.pl/>`_ API documentation.
Here you will find a complete methods documentation with examples as well.

Calling Methods
===============

In order to call a specific API Method, you need to understand few things:

* API URL: MamZdanie API calls are created by specific URL's with the
  following convention:

``BASE_URL?AUTH&METHOD&OPTIONS``

where:

* *BASE_URL* it's a base url for calling API methods and is:
  ``https://mamzdanie.org.pl/api/service``

* *AUTH* part is an API key, which you can obtain from your user profile (*Twój
  Profil*) and when invoked through API should look like:
  ``api_key=b3hf7jnms23hase8902uiosw6hj7445f``

* *METHOD* part defines, which method you want to call, eg:
  ``method=get_consultations`` - for list of methods see below.

* *OPTIONS* are each method available options, like:
  ``active=true``

Example API call should look like:

``https://mamzdanie.org.pl/api/service?api_key=b3hf7jnms23hase8902uiosw6hj7445f&method=get_consultations&active=true``

Obtaining your API key
======================

In order to use Mam Zdanie API you need to be registered as **an
organization**. To be specific:

* if you are registering as a consultation participant (register as *Jako uczestnik konsultacji*) you should choose to register an institution account (*Jestem instytucją*)

* or you can register as the organizer of the consultation - then you will
  always have access to Mam Zdanie API

Then, after you log-in, please click on your profile page (*Twój profil*), and at the bottom of the page, you will find your **API KEY** (*Twój kod autoryzacyjny API*).

API Responses
=============

When invoking Mam Zdanie API methods you will be returned with an **XML**
response which is one of the following:

* **correct response** - each method has it's own correct XML response. For
  example ``get_consultations`` method XML response looks like::

    <consultations>
        <consultation>
                <id>18855</id>
                <signature>ACTA-komentarz2012</signature>
                <subject>komentarz MAC do umowy ACTA</subject>
                <dateFrom>21-02-2012 00:00</dateFrom>
                <dateTo>22-03-2012 00:00</dateTo>
                <userName>Malgorzata Steiner</userName>
                <userId>18043</userId>
                <replies>13</replies>
                <url>http://mamzdanie.org.pl/web/guest/konsultacje/-/message_boards/message/18855</url>
                <active>true</active>
                <organizationId>18049</organizationId>
                <organizationName>Ministerstwo Administracji i Cyfryzacji</organizationName>
        </consultation>
    </consultations>

* **error response** - if an error occurs, an error XML is returned::

    <error>
        <errorDate>20-03-2012 10:57:37</errorDate>
        <errorCode>107</errorCode>
        <errorMsg>Niepoprawny parametr method</errorMsg>
    </error>

Error Responses
===============

Each error response consists of:

* ``errorDate`` - when the error occured

* ``errorCode`` - error code number

* ``errorMsg`` - error message

Here is a complete list of error codes:

* 101 - Invalid key length
* 102 - Invalid key
* 103 - Invalid ID param
* 104 - Given consultation (number) doesn't exist
* 105 - Username doesn't exist (user that published the consultation)
* 106 - Organization doesn't exist (organization that published the consultation)
* 107 - Invalid method parameter
* 500 - Server Error - contact the administrator

API Methods
===========

Here is a complete list of API Methods:

* ``get_consultations``, method options: ``active=true/false``
* ``get_consultation_details``, method options: ``id=ConsultationID``
* ``get_emiter``, method options: ``id=EmiterID``
* ``get_organization``, method options: ``id=OrganizationID``

Examples
========

This simple example written in Python shows how to get all active consultations::

        #
        # Copyright (C) 2012 Pretius Sp. z o.o.
        # 
        # Author: Robert Olejnik <rolejnik@pretius.com>
        #

        # This simple example shows how to display all active consultations

        from lxml import etree
        import requests

        MZ_BASE_URL = "https://mamzdanie.org.pl/api/service" 
        MZ_API_KEY  = "b7f2a21c345317ec23452359sla2aa08"
        MZ_URL      = MZ_BASE_URL + "?api_key=" + MZ_API_KEY + "&method="

        method = "get_consultations&active=true"
        r = requests.get(MZ_URL + method)
        consultations = r.content

        root = etree.fromstring(consultations)

        if root.tag != "error":
                for consultation in root:
                        print "Consultation:"
                        for atr in consultation:
                                print " - %s: %s" % (atr.tag, atr.text)
        else:
        	print "[ERROR] We have occurred an error:"
        	print "[ERROR] Code: %s" % root[1].text
        	print "[ERROR] Description: %s" % root[2].text


**Successful** result should be as follows::

        teon> python mamzdanie-active_consultations.py 
        Consultation:
         - id: 18855
         - signature: ACTA-komentarz2012
         - subject: komentarz MAC do umowy ACTA
         - dateFrom: 21-02-2012 00:00
         - dateTo: 22-03-2012 00:00
         - userName: Malgorzata Steiner
         - userId: 18043
         - replies: 13
         - url: http://mamzdanie.org.pl/web/guest/konsultacje/-/message_boards/message/18855
         - active: true
         - organizationId: 18049
         - organizationName: Ministerstwo Administracji i Cyfryzacji


And if an **error** occurs::

        teon> python mamzdanie-active_consultations.py 
        [ERROR] We have occurred an error:
        [ERROR] Code: 102
        [ERROR] Description: Niepoprawny klucz