Ich habe mich nun dazu entschlossen, Stück für Stück von mir intern genutzte und eigenentwickelte Frameworks, die von mir hauptsächlich im Umfeld von Django eingesetzt werden, auf GitHub zu veröffentlichen.

Den Start macht simpleapi, eine ziemlich einfache und zugleich flexible Lösung, um eine API in einem Djangoprojekt umzusetzen. simpleapi habe ich unter der MIT License veröffentlicht.

Server

simpleapi kapselt zugehörige Methoden in so genannten namespaces, die über eine Route an eine URL gebunden werden.

Eine Route kann mehrere Namespaces unterschiedlicher Version verwalten (womit bei API-Veränderungen oder Upgrades die Konsistenz beim Client durch Einführen einer neuen Namespace-Version gewahrt bleibt). Zusätzlich lassen sich Zugriffe durch einen statischen Key oder durch die Möglichkeit einer dynamischen Authentifizierungsfunktion regulieren; der Zugriff auf Namespaces kann zudem auf bestimmte IP-Bereiche limitiert werden.

Weitere flexible Parameter erlauben eine Konfiguration einzelner Methoden (z. B. die Sicherstellung von Typen einzelner Parameter).

Über Namespace-Vererbung lassen sich leicht verschiedene oder erweiterte APIs erzeugen, erweitern oder spezifizieren.

simpleapi erlaubt, das Outputformat clientseitig zu bestimmen. Standardmäßig wird JSON genutzt, XML oder andere Formate sind jedoch ebenso denkbar. Dies ermöglicht eine einfache Nutzung und Einbindung in Webanwendungen, die via Ajax auf die API zugreifen möchten. Für cross-domain Ajax-Calls bietet simpleapi JSONP an.

Ein Beispiel für eine Server-Anwendung mit multiplen Versionen findet sich folgend:

handlers.py

from simpleapi import Namespace

class JobNamespace(Namespace):
    # only allow specific ip-addresses or use a callable here for dynamic restrictions (e. g. limitation per IP)
    __ip_restriction__ = ["127.0.0.*", "78.47.135.*"]

    # you can either use a callable here (for dynamic authentication) or
    # provide a static key for authentication
    __authentication__ = "91d9f7763572c7ebcce49b183454aeb0"

    def _get_job_by_id(self, job_id):
        # get the job by job_id
        # this method isn't published to the public and isn't 
        # made accessable via API since it's missing the published-flag
        return Job.objects.get(id=job_id)

    def status(self, job_id):
        job = self._get_job_by_id(job_id)
        return job.get_status()
    status.published = True # make the method available via API
    status.types = {'job_id': str}

class OldSMSNamespace(JobNamespace):
    __version__ = 1

    def new(self, to, msg):
        # send sms ...
    new.published = True # make the method available via API
    new.methods = ('POST', ) # limit access to POST

class NewSMSNamespace(JobNamespace):
    __version__ = 2

    def new(self, phonenumber, message, sender='my website', priority=5):
        # send sms ...
    new.published = True # make the method available via API
    new.methods = ('POST', ) # limit access to POST
    new.types = {'priority': int} # ensure that priority argument is of type int

urls.py

from simpleapi import Route
from handlers import OldSMSNamespace, NewSMSNamespace, FaxNamespace

urlpatterns = patterns('',
    (r'^job/fax/$', Route(FaxNamespace)), # Route with exact one namespace
    (r'^job/sms/$', Route(OldSMSNamespace, NewSMSNamespace)), # Route can hold different versions of namespaces
)

Client

Anders als viele andere API-Frameworks bietet simpleapi eine Client-Bibliothek an, die es ermöglicht, aus einer einfachen Python-Anwendung heraus (natürlich auch aus Django) Zugriff auf die API zu nehmen. Dabei unterstützt die Client-API selbstredend auch den Zugriff auf unterschiedliche API-Versionen oder kann einen Zugriffsschlüssel übertragen.

Ein Beispiel für eine Client-Anwendung findet sich hier:

from simpleapi import Client

SMS = Client(ns='http://yourdomain.tld/api/job/sms/', version=2)
new_sms = SMS.new(
    phonenumber="+49 123 456789",
    message="Short test"
)

SMS.set_version(1) # back to the old API-version (which takes different named arguments)

new_sms = SMS.new(
    to="+49 123 456789",
    msg="Short test"    
)

Mehr Informationen sind in der README von simpleapi zu finden. Ich habe dem Repository eine lauffähige Demo-Anwendung beigefügt. Wenn jemand Interesse an simpleapi gefunden hat, darf er gerne das Repository forken und Pull-Requests stellen.

Ich hoffe, dass simpleapi dem ein oder anderen hilft, wenn er mal wieder auf der Suche nach der Frage ist: Wie realisiere ich eine API in Django?