.. _REF_BASICS:

Grundlagen
##########


Rolle des MMXL Web Service
**************************

Der :term:`MMXL` :term:`Web Service` macht die Funktionen der MMXL Schnittstelle des :term:`Medinet`
Prozesses via :term:`HTTP` verfügbar. Während die originale MMXL Schnittstelle von
Medinet :term:`XML` zur Darstellung der Datenstrukturen verwendet, konvertiert der MMXL
Web Service diese an seinem öffentlichen :term:`API` in :term:`JSON` und wieder zurück, um die
Benutzung der MMXL Funktionen für Web Clients zu vereinfachen.

Die Schnittstelle des MMXL Web Service ist nach dem :term:`REST` Paradigma (`Wiki REST`_) gestaltet.
D.h. die Anforderungen werden direkt mit HTTP an unterschiedliche :term:`URL`\s geschickt und die Antworten
kommen direkt in den HTTP Nachrichten - meist als JSON- Objekte dargestellt - zurück. Insbesondere wird kein
gesondertes Protokoll wie z.B. :term:`SOAP` oder :term:`XML-RPC` verwendet.

Für die Parameter und Resultate der MMXL Web Service Operationen wird weitgehend
JSON verwendet, da es besonders einfach von :term:`JavaScript` verwendet werden kann,
aber auch geeignete Bibliotheken für viele andere Programmiersprachen zur Verfügung stehen.


Versionierung des REST Interfaces
*********************************

Durch Voranstellen eines Präfix `v`\i (i = 1..n) an die :term:`URL`\s der
Routen erfolgt eine Versionierung der MMXL APIs. Aktuell gibt es `v1`
(Version 1) des API. Die komplette URL einer Operation setzt sich daher wie
folgt zusammen:

    HOST_ADDRESS/v1/ROUTE

zum Beispiel könnte die URL zum Abruf aller vorliegenden Analysen wie folgt
lauten:

    https://mmxlapi.comsulting.net/v1/analyses?api_key=API_KEY

In den folgenden Dokumentationen der einzelnen Routen und Operation wird der
Versionspräfix in der Regel nicht dargestellt. Er ist sinngemäß jeder Route
wie hier beschrieben voranzustellen.


.. _Wiki REST: http://de.wikipedia.org/wiki/Representational_State_Transfer