HTTP API

Oltre all'utilizzo dei vari driver visti nelle lezioni precedenti, tipicamente pensati per permettere l'interazione con MongoDB con i vari linguaggi di programmazione, esistono diverse soluzioni basate sulla creazione (eventualmente automatica) di API REST o interfacce HTTP. Il sito ufficiale di MongoDB elenca diverse soluzioni; tra queste, ne vedremo una molto semplice, che sfrutta un server HTTP scritto in Python per realizzare un'interfaccia in grado di interrogare il nostro database senza alcun vincolo specifico sul linguaggio di programmazione da utilizzare: Sleepy Mongoose.

Installazione e avvio

Assumendo, ovviamente, di avere già installato MongoDB, dovremo innanzitutto installare il driver per Python PyMongo. Abbiamo già visto come fare in una lezione precedente, ma per semplicità riportiamo di seguito come installarlo facendo ricorso ad easy_install:

$ easy_install pymongo

A questo punto non resta che scaricare Sleepy Mongoose, che è disponibile gratuitamente su GitHub. Una volta scaricato, dall'interno della directory contenente il codice, avviamo lo script che funge da server HTTP come segue:

python httpd.py

Se tutto andrà come previsto, vedremo il seguente output, a conferma del corretto funzionamento del server HTTP:

=================================
|      MongoDB REST Server      |
=================================
listening for connections on http://localhost:27080

Possiamo effettuare un'ulteriore verifica, effettuando una richiesta HTTP al seguente URL:

http://localhost:27080/_hello

Se tutto fuzniona bene, riceveremo come risposta una citazione di Star Wars.

Non ci resta, a questo punto, che imparare ad usare l'intefaccia HTTP messa a disposizione da Sleepy Mongoose.

Utilizzare Sleepy Mongoose

La prima cosa da fare per utilizzare l'interfaccia HTTP di Sleepy Mongoose è connettersi al database. Per farlo, è necessario inviare una richiesta HTTP POST all'URL http://localhost:27080/_connect, contenente come payload la stringa server=localhost:27017. Ovviamente localhost può essere modificato come vogliamo (in base all'IP su cui faremo girare il server HTTP), mentre la porta 27017 è quella di default utilizzata da Sleepy Mongoose. Per semplicità, d'ora in avanti utilizzeremo la sintassi di curl, comando diffuso nei sistemi UNIX-like, e pensato proprio per effettuare richieste HTTP. In questo caso, quindi, la connessione al database avviene come segue:

$ curl --data server=localhost:27017 'http://localhost:27080/_connect'

Si noti che l'opzione --data è usata proprio per effettuare richieste HTTP POST, mentre il parametro che segue (la stringa server=localhost:27017) è il payload.

Vediamo adesso come inserire i dati all'interno del nostro database:

$ curl --data 'docs=[{"x":1}]' 'http://localhost:27080/foo/bar/_insert'

Ancora una volta, abbiamo effettuato una richiesta HTTP POST. In questo caso, il documento da inserire è specificato nel payload ({"x":1}), mentre la URL permette di specificare che foo è il nome del database, e bar la collection in cui inseriremo il documento. L'ultima parte della URL (_insert) rappresenta l'operazione da effettuare.

A questo punto, possiamo verificare che l'inserimento sia andato a buon fine sfruttando una ulteriore richiesta HTTP, questa volta GET, che ci permette di effettuare una query di lettura:

$ curl -X GET 'http://localhost:27080/foo/bar/_find'

Il risultato sarà il seguente:

{"ok": 1, "results": [{"x": 1, "_id": {"$oid": "4b7edc9a1d41c8137e000000"}}], "id": 0}

Il valore di ritorno della query contiene sempre 3 campi:

• ok, valorizzato ad 1 nel caso in cui la query ha avuto successo
• results, contenente un array di documenti ottenuti dal database (in altre parole, il risultato vero e proprio dell'esecuzione di find)
• id, rappresentante un identificativo per questa particolare query

A questo punto, proviamo ad eseguire una rimozione di un documento:

$ curl --data 'criteria={"x":1}' 'http://localhost:27080/foo/bar/_remove'

Ancora una volta, l'operazione è implementata come richiesta HTTP POST, trattandosi di una modifica. Se tutto va a buon fine, otterremo la risposta seguente:

{"ok" : 1}

Infine, non ci resta che provare una semplice operazione di update. Prima, però, aggiungiamo 2 nuovi documenti (dal momento che la rimozione appena effettuata ha, di fatto, svuotato il nostro database di prova).

$ curl --data 'docs=[{"x":1},{"x":3}]' 'http://localhost:27080/foo/bar/_insert'

Adesso, agggiorniamo il documento {"x":1} come segue:

$ curl --data 'criteria={"x":1}&newobj={"$inc":{"x":1}}' 'http://localhost:27080/foo/bar/_update'

Non ci resta che dare un'occhiata ad un esempio in cui utilizziamo _find con alcuni criteri di ricerca aggiuntivi. Per inserire questi criteri all'interno della URL, dovremo eseguire l'escape dei caratteri { e }. Esistono diversi tool, anche online, che eseguono questa operazione (oltre alle innumerevoli API disponibili e preinstallate su svariati linguaggi di programmazione). Proviamo quindi a richiedere il documento {"x":2}:

curl -X GET 'http://localhost:27080/foo/bar/_find?criteria=%7B%22x%22%3A2%7D'

Ogni ulteriore informazione sull'uso di Sleepy Mongoose può essere reperita sulla Wiki ufficiale del progetto.