Introduzione alle API REST di WP

Con il suo inizio nel 2003, WordPress è cresciuta da una semplice piattaforma di blogging, ad un sistema di gestione dei contenuti a pieno titolo. In questi ultimi anni, è abbastanza maturato da soddisfare la necessità della stragrande maggioranza del pubblico online e questo è il motivo per cui viene utilizzato dal più del 20% del web.

WordPress è stato arricchito da molte nuove caratteristiche, ed una delle ultime ad essere aggiunta è la REST API che consente alle altre apps e piattaforme di interfacciarsi con WordPress. È un'aggiunta rivoluzionaria che aiuterà gli sviluppatori  a realizzare applicazioni personalizzate e sistemi integrati con WordPress. Poiché fornisce la capacità di aggiungere e recuperare il contenuto da qualsiasi altro client o sito, senza il bisogno di installare WordPress su quel sito, WordPress può essere utilizzato con qualsiasi linguaggio di programmazione o piattaforma.

In questa serie di tutorial, parleremo delle WP REST API e di come possono essere usate per creare dei servizi di user-experience che altrimenti sarebbero impossibili, o quantomeno ardui da realizzare con Wordpress. Dapprima daremo un  occhiata ai concetti base includendo REST e JSON , poi esploreremo le opzioni a nostra disposizione nell'ambito delle WP REST API.

Sotto, ci sono una serie di risorse che ritengo siano utili per cogliere i concetti base inclusi HTTP, REST e JSON. Vi raccomando vivamente di dargli un occhiata se non l'avete ancora fatto.

• A Beginner’s Guide to HTTP and REST di Ludovico Fischer
• Demystifying REST di Jeffrey Way
• Introducing JSON di Michael James Williams
• Storing Data with JSON (screencast) di Andrew Burgess

Prima di partire con il nostro argomento, diamo uno sguardo a ciò che in realtà è l'architettura REST ed anche acquisire familiarità con la sua terminologia comune.

Torniamo a scuola con REST

Per iniziare l'argomento, diamo un'occhiata all'architettura REST (Representational State Transfer) ed a molti dei suoi concetti più comuni. Capirli è essenziale quando si sviluppano applicazioni utilizzando lo stile di architettura REST.

REST è uno stile di architetturale che aiuta a creare ed organizzare un sistema distribuito. Descrive il web come un'applicazione distribuita ipermedia, le cui risorse collegate comunicano scambiando rappresentanzioni dello stato delle risorse.

Le risorse sono gli elementi costruttivi principali dell'architettura REST In realtà, sono i principali elementi costitutivi del web stesso, nella misura in cui il web è noto come "risorsa-oriented".

Quando si parla di WordPress, queste risorse sono entità distinte come post, pagine, commenti, utenti e custom post type ecc. Per interagire con le risorse, vengono utilizzati gli URI (Uniform Resource Identifier) e come suggerisce il nome, è un identificatore di una risorsa.

Un servizio RESTful considera gli URI come il modo principale per indirizzare una risorsa sottostante. Queste risorse possono avere diverse rappresentazioni. Ad esempio, un file immagine potrebbe essere disponibile nei formati JPG. GIF, o. PNG. La relazione tra risorse e URI è uno a molti. Un URI può solo puntare ad una risorsa specifica, ma una risorsa può avere più di un URI.

L'elenco di tutte le risorse attualmente supportate dall'API REST di WP è come quella sotto:

• Posts
• Pagine
• Media (foto, video)
• Custom Post Types
• Post Meta
• Revisoni
• Commenti
• Termini
• Utenti

Possiamo eseguire diverse azioni su queste risorse utilizzando verbi HTTP.

Verbi HTTP

Ad un'API REST fondamentalmente è consentito eseguire operazioni CRUD (crea leggi aggiorna elimina) sulle risorse utilizzando il protocollo HTTP. Per questo scopo, il REST si avvale di un insieme limitato di verbi per le richieste HTTP come indicato di seguito:

1. GET: Utilizzato per leggere o recuperare una risorsa
2. POST: Utilizzato per creare una nuova risorsa
3. PUT: Utilizzato per aggiornare una risorsa
4. DELETE: Utilizzato per eliminare una risorsa
5. HEAD: Utilizzato per verificare se esiste una risorsa senza restituire la sua rappresentazione
6. OPTIONS: Utilizzato per recuperare tutti i verbi supportati da una risorsa

In un servizio RESTful, questi verbi hanno un significato ben definito. I primi quattro verbi in questo elenco sono parte di azioni CRUD cioè recuperare, creare, aggiornare ed eliminare entità. Gli ultimi due verbi aiutano il client a determinare se esiste una risorsa e cosa possono eseguire i verbi HTTP, per ulterirori operazioni.

Una richiesta GET recupera informazioni ed è idempotente cioè un client può chiamarla molte volte ma non influenzerà lo stato di una risorsa.

Per ottenere tutti i post utilizzando l'API REST di WP, usiamo l'endpoint seguente:

1

GET wp/v2/posts

L'endpoint sopra citato restituisce una collezione di tutte le entità post.

Quando viene attivato l'endpoint seguente, restituisce una particolare entità cioè un post con un id di 100:

1

GET wp/v2/posts/100

Una richiesta POST crea una nuova entità e una richiesta PUT sostituisce tale entità con una nuova versione.

La seguente richiesta POST può essere utilizzata per creare un nuovo post (invio lungo il corpo della richiesta che ci porteremo un'occhiata nella parte successiva della serie) utilizzando l'API REST di WP:

1

POST wp/v2/posts

E la seguente richiesta PUT aggiornerà un post con un id 100:

1

PUT wp/v2/posts/100

Una richiesta di DELETE consente di eliminare una risorsa dal sistema. Questo tipo di richieste, insieme alla richiesta PUT sono ripetibili, il che significa che la chiamata di questi metodi avrà lo stesso effetto sul sistema. Ad esempio, se chiamate una richiesta PUT più volte su una risorsa (con gli stessi argomenti), il risultato sarà lo stesso. Lo stesso vale per una richiesta di DELETE. Eliminazione di una risorsa più volte avrà lo stesso effetto cioè la risorsa verrà eliminata (o restituirebbe un errore in caso di una risorsa già eliminata).

Oltre a queste azioni CRUD, un servizio RESTful fornisce due verbi in più che sono OPTIONS e HEAD. Questi verbi sono utili quando un cliente ha bisogno di controllare quali sono le risorse disponibili sul sistema e le azioni che le supportano, fornendo così al client  un modo per auto-documentari, esplorare ulteriormente il sistema ed eseguire azioni. Vedremo questi due metodi in azione più avanti in questo tutorial.

Ulteriori informazioni su Percorsi e gli Endpoint

Notate che nel primo esempio sopra, abbiamo utilizzato l'endpoint seguente:

1

GET wp/v2/posts

Gli endpoint sono funzioni che disponibili tramite l'API ed eseguono diverse azioni come recuperare un post (che stiamo facendo qui sopra), creare  un nuovo utente o aggiornare un post meta. In alternativa, possiamo dire che un endpoint attiva un metodo che esegue un'attività specifica. Questi endpoint dipendono dal verbo HTTP associato con loro. Nell'esempio precedente, abbiamo usato il verbo GET per recuperare tutti i messaggi.

Il percorso per l'endpoint di cui sopra è il seguente:

1

wp/v2/posts

Un itinerario è fondamentalmente un nome per accedere all'endpoint. Un itinerario può avere più endpoint basati su verbi HTTP. Così il percorso di cui sopra usa l'endpoint seguente per creare un nuovo post:

1

POST wp/v2/posts

Questo endpoint, quando attivato con parametri forniti, creerà una nuova entità post.

Considerate l'itinerario seguente :

1

wp/v2/posts/100

Questo percorso fa riferimento ad una entità Post che ha un id di 100. Ha i seguenti tre endpoint:

1. GET wp/v2/post/100:  può essere utilizzato per recuperare il post con id 100. Si attiva il metodo get_Item ().
2. PUT wp/v2/post/100: può essere utilizzato per aggiornare il post con un id di 100. Si attiva il metodo update_item().
3. DELETE wp/v2/post/100: Elimina il post che ha un id di 100. Si attiva il metodo delete_item().

Nella parte finale di questa serie ne sapremo di più sugli elementi interni dell'API REST di WP, la  struttura della classe ed i  metodi interni.

Adesso aggiornarniamo la nostra conoscenza su alcuni comuni codici di risposta HTTP e cosa significano.

Codici di risposta HTTP

Un server risponde ad una richiesta restituendo una risposta contenente un codice di stato HTTP. Questi codici sono numeri con significati predefiniti associati ad essi. Ad esempio,chiunque utilizzi il web ha familiarità con il codice di stato 404, riassume che la risorsa, che sta cercando l'utente, non è stata trovata.

La risposta del server è dipendente anche dal tipo di verbo HTTP o metodo che usiamo nella richiesta inviata, come vedremo successivamente.

Di seguito alcuni dei codici di risposta HTTP comuni con il loro significato, che si possono incontrere quando si lavora con l'API REST di WP e il loro significato:

• 200 - OK: Significa che la richiesta è stata completata correttamente e il server ha restituito la risposta. In genere restituito dopo una richiesta GET riuscita.
• 201 - Creato: In genere restituito dopo una richiesta POST conclusa con successo. Riassume che la risorsa è stata creata.
• 400 - Richiesta errata: Viene restituito dal server quando una richiesta è stata inviata con alcuni parametri mancanti o non validi. In genere restituito in risposta a richieste  POST o PUT.
• 401 - Non Autorizzato: Significa che l'utente non è autorizzato ad eseguire determinate azioni. Ad esempio, un utente tenta di creare o eliminare una risorsa senza fornire credenziali di autenticazione.
• 403 - Proibito: Significa che il server capito la richiesta, ma si rifiutò di completarla a causa dell'autenticazione. Accade quando un utente fornisce le credenziali di autenticazione, ma non ha diritti sufficienti per eseguire l'azione.
• 404 - Non Trovato : La maggior parte (in) famoso di tutti i codici di stato. Riassume che la risorsa, che l'utente stava cercando, non è stata trovata.
• 405 - Metodo non Consentito: significa che un verbo HTTP fornito nella richiesta non era supportato dalla risorsa. Un esempio potrebbe essere un utente tenta di aggiornare una risorsa in sola lettura.
• 410 - Andata: Significa che una risorsa è stata spostata in un'altra posizione. Un esempio potrebbe essere cercate di eliminare una risorsa già eliminata che è stata spostata nel Cestino.
• 500 - internal Server Error: Viene restituito quando un server viene rilevata una condizione imprevista e non completa la richiesta.
• 501 - Non Implementato: Significa che il server non supporta la funzionalità per completare la richiesta. Si verifica in genere quando un server riceve un metodo di richiesta che non riconosce.

Esamineremo questi verbi HTTP e codici di risposta più strettamente quando abbiamo effettivamente iniziare a lavorare con le API. Ma prima di allora, diamo un'occhiata alle ragioni per l'utilizzo di API REST con WordPress e i vantaggi che arreca sia allo sviluppatore che all'utente. Dopo tutto, devi essere sinceramente interessato a seguirmi durante tutta questa serie.

Perché usare API REST JSON per WordPress?

REST e JSON insieme forniscono un meccanismo per la creazione di potenti applicazioni che utilizzano WordPress back-end. Gli esempi più prossimi sono le applicazioni mobili che richiedono lo scambio di dati tra il client (dispositivo) e il server Tenendo in considerazione le limitazioni della larghezza di banda quando si utilizza la connessione dati da cellulare, JSON fornisce soluzioni basate su XML un'alternativa leggera.

Poiché JSON è un formato basato su testo per la memorizzazione di dati, può essere utilizzato senza soluzione di continuità con la maggior parte dei linguaggi di programmazione. Quindi JSON serve come un connettore globale quando lo scambio di dati tra piattaforme diverse che è ugualmente leggibile dalle macchine sia e gli esseri umani.

Con l'uso di API come quella in discussione, il contenuto del vostro sito WordPress non è solo limitato a se stesso, ma può essere acceduto da altri siti e client. Come API espone alcune parti delle funzionalità interne, i client remoti possono interagire con il tuo sito per aggiornare o creare nuovi contenuti. Permette anche di recuperare alcuni contenuti da un sito esistente di WordPress e mostrarlo su qualche altro sito.

Con l'avvento dei Framework JavaScript lato client come Angular, Backbone o Ember,è diventato possibile utilizzarli per arricchire la web experience dell' utente, mentre ancora utilizzo il back end di WordPress.

Detto questo, alcuni possibili use case per l'API REST di WP sono:

• Mobile apps
• Pannelli admin personalizzati per WordPress
• Applicazioni Pagina Singola (SPAs)
• Integrazione con altre piattaforme di lato server (come Ruby, .NET e Django, ecc.)
• e molto altro ancora...

Si apre davvero un nuovo mondo di possibilità, dove l'unico limite è la propria immaginazione.

Una breve storia delle API REST JSON in WordPress

Prima di JSON  baseto sul protocollo API REST, per interagire in remoto con Word Press veniva utilizzata l' API XML-RPC che è ancora parte del core di WordPress. Il problema con XML è che non è più leggero, come il formato JSON e la sua analisi non è efficiente. Attraversamento di un oggetto in XML da un gran mal di testa, mentre in JSON è più facile come il movimento di un oggetto JavaScript nativo.

Il primo plugin REST API mai introdotto per WordPress è stato API JSON che è stato rilasciato nel 2009. Fu costruito presso il Museo di Arte Moderna per il loro blog Inside/Out. Il Front- end di questo blog è stato realizzato con Ruby on Rails, per recuperare i post ed aggiungere i commenti dal backend WordPress è stata sviluppata un API. Questo plugin fornisce interfacce per recuperare contenuti e inviare commenti per il backend di WP. Anche se non aggiornato per più di due anni, questo plugin è ancora presente nel repository ufficiale ed è disponibile.

A parte il plugin API JSON, WordPress.com ha già fornito API JSON tramite il plugin JetPack.

L'API REST di WP, per come lo conosciamo oggi,  è un plugin di funzionalità che è stato proposto da Ryan McCue come parte del GsoC (Google Summer of Code) 2013. Non è stato ancora incluso (completo) nel core di WordPress , lo sarà in una futura versione.  La versione corrente del plugin la  2.0 è in stato beta ed è parzialmente inclusa nel core di WordPress nella versione 4.4 Si tratta di un progetto guidato dalla community da Ryan McCue e Rachel Baker. La pagina repository ufficiale del plugin è disponibile su GitHub e la documentazione ufficiale può essere trovata sul suo sito Web.

Stato attuale dell'API REST di WP

Come accennato in precedenza che l'API REST di WP è attualmente in stato di plugin e si sta sviluppando attivamente su GitHub. È stato parzialmente incluso nel nucleo di WordPress in versione 4.4 e Ryan ha descritto il piano nella sua proposta di Unione su WordPress.org.

Secondo la proposta di Unione, l'API REST di WP verrebbero incorporata nel nucleo di WP in due fasi come descritto di seguito:

Unione di codice di infrastruttura

Secondo la proposta, nella fase iniziale, solo il codice del livello di infrastruttura verrà Unito nel nucleo WP nella versione 4.4. Questo codice di infrastruttura è la base reale dell'API REST WP in quanto include JSON serializzazione/deserializzazione, collegamento, l'incorporamento e il più importante di tutti - lo strato di routing che spinge l'API. Questo codice non include gli endpoint e loro classi controller, ma fornisce una base per la creazione di API all'interno di WordPress.

Al momento della scrittura, questo è passato allo stato completato e il codice dell'infrastruttura è stato Unito nel nucleo di WordPress in versione 4.4.

Unione degli endpoint

Gli endpoint per post, pagine, gli utenti e tassonomie ecc saranno incorporati nel nucleo WP nella versione 4.5, nella release successiva all'Unione del codice dell' infrastruttura. Gli endpoint sono ciò che rende l'API utile ai clienti generali. Essi comprendono molta complessità ed includono il mapping dei dati esterni in formato JSON per tipi di dati nativi di WordPress e viceversa. Essi rappresentano il codice di due terzi dell'API stessa con circa 5500 righe.

La strategia è quello di costruire la fiducia degli sviluppatori nelle API da prima fornendo il codice infrastrutture nel nucleo. Ciò consentirebbe agli sviluppatori di temi e plugin di creare API personalizzate da includere nei loro temi e plugin. Ma poiché, gli endpoint non saranno inclusi in questa fase, questo limiterebbe inizialmente l'utilità dell'API .

Il divario tra le due versioni darebbe gruppo committente del WP core  abbastanza tempo per rivedere gli endpoint dell'API.

Un altro vantaggio che l'API REST di WP porterebbe alla comunità di WordPress, è l'utilizzo di GitHub per controllare il progetto in versioni. Poiché tutti i contributi di WordPress sono fatti attraverso SVN e Trac, il team di API REST di WP è abbastanza fiducioso su come migliorare il processo di contribuzione, colmando il divario tra Trac e GitHub.

Dopo l'Unione dell'API nel nucleo, possiamo sperare di vedere rapidi sviluppi in altri settori tra cui l'autenticazione OAuth 1.0 a.

Strumenti del mestiere

Per iniziare il test con l'API REST di WP abbiamo bisogno di un client HTTP che verrà utilizzato per inviare richieste al server e visualizzare la risposta. E 'davvero una questione di scelta,io utilizzerò Postman per Google Chrome in questa serie. Altre alternative a Postman sono:

• REST Easy per Firefox
• HTTPie per la riga di comando

Postino ci permette di creare rapidamente richieste HTTP dei diversi metodi, mostra la risposta dalla configurazione del server e prova l'autenticazione. Tutte queste caratteristiche saranno estremamente utili quando si lavorerà con l'API REST di WP.

La prossima cosa che dobbiamo avere sul nostro server è WP-CLI. Con WP-CLI, possiamo gestire in remoto la nostra installazione di WordPress all'interno della console senza la necessità di aprire la finestra del browser. Dovremo usare WP-CLI nella parte successiva di questa serie quando si configura l'autenticazione OAuth 1.0 a. Potete trovare le istruzioni dell'installazione sul sito ufficiale.

Oltre a un client HTTP e WP-CLI, abbiamo bisogno anche di dati demo per la nostra installazione di WordPress. Vi suggerisco di controllare Theme Unit Test (XML) o il plugin  Demo Data Creator che permette di creare più post, pagine e utenti.

L'installazione del Plugin

Al momento della stesura di questo tutorial, la versione stabile è la 1.2.2 che può essere trovata sul repository ufficiale. In questa serie, lavoreremo con la versione 2.0 come se esso fosse stato riscritto da zero e contesse molte modifiche importanti. Si può prendere la versione 2 beta dalla  pagina ufficiale del plugin o dal suo repository su GitHub.

Notate che non è altamente consigliabile installare la versione beta corrente nell'ambiente di produzione. Ho impostato un ambiente locale di WordPress e vi consiglio di farlo per lo sviluppo e test.

Per installare il plugin dal repository di GitHub, aprire il terminale e tirare il plugin dopo entrare nella vostra plugin directory   wp-content/plugins/directory:

1

$ git pull https://github.com/WP-API/WP-API.git

Il plugin sarà scaricato nella cartella  /WP-API/

È possibile attivarla dal vostro admin di WordPress a continuare il test con esso.

Affinchè il plugin WP REST API funzioni, è necessario abilitare i Permalink con WordPress. Ciò presuppone che sappiate già di eseguire questa azione di base. Se non siete in grado, non ti preoccupatevi è un argomanto che WordPress.org ha coperto.

Valutare la disponibilità dell' API

E' dopo aver installato il plugin, che possiamo valutare la disponibilità delle API sul nostro server. Non siamo limitati all'utilizzo dell'API al solo nostro sito, infatti, l'usiamo su qualsiasi sito che lo abbia installato e attivato. Per controllare l'API su altri siti, possiamo inviare una richiesta HEAD al sito come indicato di seguito utilizzando il vostro client HTTP:

1

$ HEAD http://someothersite.com/

Nell'intestazione di risposta verrà restituito qualcosa come la  seguente:

il Link header point nella root  dell'API WP che è nel nostro caso è la seguente:

1

http://localserver/wordpress-api/wp-json/

L'API può essere scoperto anche attraverso JavaScript nel browser (o jQuery) eseguendo una ricerca del DOM per l'elemento appropriato <link>simile al seguente:

1

(function( $ ) {

2

    var $link = $( 'link[rel="https://github.com/WP-API/WP-API"]' );

3

  var api_root = $link.attr( 'href' );

4

})( jQuery );

Da qui possiamo iniziare a recuperare il contenuto dal sito tramite l'API REST di WP. Per favore notate che solo delle richieste autenticate possono modificare o aggiornare il contenuto del sito e sto salvando l'oggetto della configurazione dell'autenticazione per le prossime due parti di questa serie.

Cosa vedremo dopo?

In questa parte introduttiva della serie abbiamo imparato molto circa l'architettura del REST, l'API REST di WP e dello stesso HTTP. Abbiamo guardato prima concetti base come architettura REST e come può aiutare gli sviluppatori a creare applicazioni migliori. Poi abbiamo imparato su HTTP, verbi e tipi di risposta. Abbiamo anche visto breve storia sulle API in WordPress e come l'API REST di WP è diverso dai suoi predecessori.

Nella parte finale di questo tutorial, abbiamo installato il plugin da GitHub. Dopo che noi stessi abbiamo familiarizzato con una richiesta HEAD che può essere utilizzata per determinare la disponibilità delle API sul nostro server, così come su altri server.

Dopo aver impostato l'ambiente di lavoro base siamo pronti a lavorare con le funzionalità che fornisce l'API REST di WP. Nella parte successiva della serie, ci occuperemo modi per impostare i metodi di autenticazione supportati dall'API. Questi metodi di autenticazione sarà richiesti quando si invia la richiesta per recuperare, creare, aggiornare o eliminare contenuto. Quindi rimanete sintonizzati.