Introduzione alla REST API

Questo testo è stato tradotto utilizzando l’IA. Se desideri visualizzare il testo originale in inglese, fai clic qui.

La REST API di WordPress.com consente di visualizzare, creare o modificare contenuti su qualsiasi sito WordPress.com, nonché su qualsiasi sito self-hosted (WordPress.org) connesso tramite Jetpack. Questo include non solo articoli del blog e pagine, ma anche commenti, tag, categorie, media, statistiche del sito, notifiche, impostazioni di condivisione, profili utente e molte altre funzionalità di WordPress.com.

Alcune richieste (ad esempio l’elenco dei post pubblici) non richiedono autenticazione, ma qualsiasi azione che richiederebbe a un utente di essere connesso (come la creazione di un post) necessita di un token di autenticazione.

Per effettuare richieste autenticate, sarà prima necessario creare un account su WordPress.com se non ne possiedi già uno.

Come utilizzarla

Esistono due modi per esplorare gli endpoint disponibili per la REST API di WordPress.com:

• La pagina di documentazione di riferimento della REST API elenca gli endpoint disponibili e descrive in dettaglio l’input e l’output di ciascuno, insieme a codice di esempio in curl e PHP.
• La console di sviluppo della REST API consente di costruire e provare richieste API reali.

Effettuare richieste non autenticate è semplice. Poiché non sono richieste intestazioni speciali, puoi anche aprire questa direttamente nel browser per vedere cosa restituisce: https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/?number=2&pretty=true

Effettuare richieste autenticate richiede alcuni passaggi aggiuntivi. Tutte le richieste autenticate alla REST API di WordPress.com richiedono un token di accesso OAuth2. Questo token deve essere ottenuto dagli endpoint OAuth2 di WordPress.com e può essere acquisito attraverso diversi flussi, i più rilevanti dei quali sono:

1. Flusso OAuth2 completo – Gli utenti autorizzano la tua applicazione tramite l’interfaccia di WordPress.com, concedendo permessi specifici. Questo è l’approccio più sicuro ed è richiesto per le applicazioni di terze parti.
2. Scambio diretto di token tramite credenziali – Usa una password applicazione con grant_type=password per ottenere direttamente un token per i tuoi siti. Questo bypassa il passaggio di autorizzazione dell’utente ma richiede le tue credenziali WordPress.com.

Entrambi i metodi producono lo stesso tipo di access token OAuth2 che includi nelle richieste come Authorization: Bearer YOUR_ACCESS_TOKEN. L’approccio basato su token garantisce una sicurezza coerente e consente il controllo degli accessi per singola applicazione.

Raccomandiamo l’autenticazione OAuth2 come il modo più sicuro e granulare per accedere alla REST API di WordPress.com. Se hai già familiarità con OAuth2, puoi passare direttamente alla documentazione tecnica.

OAuth2 consente alla tua applicazione di agire per conto di un utente senza mai vedere la sua password. Ecco come funziona: quando qualcuno vuole usare la tua app con il proprio account WordPress.com, la tua app lo reindirizza su WordPress.com per effettuare l’accesso. WordPress.com mostra esattamente cosa la tua app vuole fare (come leggere i suoi articoli o crearne di nuovi) e chiede se è d’accordo. Se accetta, WordPress.com fornisce alla tua app uno speciale access token. Questo token è come una chiave temporanea che consente alla tua app di fare solo le cose che l’utente ha autorizzato.

Puoi immaginarlo come una conversazione a tre:

• Utente: «Vorrei pubblicare un articolo tramite questo client API.»
• Client (App): «Ok. Ehi, WordPress.com, vorrei fare qualcosa per conto di questo utente. Puoi chiedergli se è d’accordo?»
• WordPress.com: «Certo. Ehi, utente, va bene se il Client agisce per tuo conto?»
• Utente: «Sì, va bene. Mi fido di questo client per compiere azioni per mio conto in futuro.»
• WordPress.com: «Ok, Client, ecco un token che ti permetterà di compiere azioni per conto di questo utente. Tienilo segreto. Tienilo al sicuro.»

Una volta che il Client (App) ha ottenuto il token, può effettuare richieste autenticate a WordPress.com. Ecco come funziona una tipica interazione:

• Client (App): «Ciao WordPress.com, vorrei creare un nuovo articolo. Ecco il mio access token che dimostra che sono autorizzato ad agire per conto dell’utente, insieme al titolo dell’articolo, al contenuto e ad altri dettagli.»
• WordPress.com: «Ho validato il tuo token e confermato che hai il permesso di creare articoli. L’articolo è stato creato e pubblicato con successo. Ecco la risposta con l’ID del nuovo articolo, l’URL e altri metadati.»

Questo flusso di autenticazione basato su token OAuth2 fornisce un controllo degli accessi sicuro e granulare: il Client può eseguire solo le azioni che l’utente ha esplicitamente autorizzato durante il flusso OAuth. Il token può essere revocato in qualsiasi momento se necessario, e WordPress.com verifica i permessi del token ad ogni richiesta.

Il vantaggio di questo sistema è che gli utenti mantengono il controllo. Possono vedere esattamente cosa la tua app sta richiedendo e possono revocare l’accesso in qualsiasi momento. La tua app non memorizza mai le password e, se un token viene compromesso, l’impatto riguarda solo l’accesso di quella singola app, non l’intero account dell’utente.

Probabilmente hai già visto questo processo quando effettui l’accesso a siti web utilizzando il tuo account Google o Facebook. Il funzionamento è lo stesso: fai clic su “Accedi con Facebook,” vieni reindirizzato su Facebook per confermare e poi vieni riportato al sito originale.

Dal punto di vista della tua app, il processo prevede alcuni passaggi:

• Per prima cosa, registri la tua applicazione su WordPress.com per ottenere un client ID.
• Poi indirizzi gli utenti verso WordPress.com con un link speciale che include il tuo client ID e indica a WordPress.com dove rimandare l’utente.
• Quando gli utenti autorizzano la tua app, WordPress.com li reindirizza alla tua app con un codice di autorizzazione. Scambi questo codice con un access token utilizzando il tuo client secret, e poi puoi usare quel token per effettuare richieste API per conto dell’utente.

Una volta ottenuto un access token, effettuare richieste autenticate è semplice. Includi il token nell’header Authorization delle tue richieste in questo modo: Authorization: Bearer your_token_here.

Per i dettagli completi sull’implementazione, esempi di codice e best practice di sicurezza, consulta la guida all’autenticazione OAuth2.

Struttura dell’URL di base

La REST API di WordPress.com fornisce una struttura standardizzata dell’URL di base che garantisce un accesso coerente per tutti i tipi di sito, le configurazioni di hosting e i namespace dell’API. Tutti gli endpoint disponibili sono organizzati e raggruppati sotto diversi namespace (come wp, rest e wpcom) e le rispettive versioni (come v1, v1.4, v2, v4), fornendo una separazione logica tra le diverse funzionalità dell’API e consentendo strategie di versionamento indipendenti. Questo approccio unificato semplifica l’integrazione con l’API ed elimina la necessità di determinare formati URL diversi in base alle caratteristiche del sito o alle versioni dell’API.

Per informazioni dettagliate sui namespace disponibili, le loro versioni e gli endpoint forniti da ciascun namespace, consulta la documentazione Namespace e versioni.

Struttura generale dell’URL

Tutti gli endpoint della REST API di WordPress.com seguono questo schema standardizzato:

https://public-api.wordpress.com/{namespace}/{version}/{endpoint}

Segnaposto:

• {namespace}: Il namespace dell’API (ad es. ‘rest’, ‘wp’, ‘wpcom’)
• {version}: La versione dell’API (ad es. ‘v1’, ‘v1.4’, ‘v2’, ‘v4’)
• {endpoint}: L’endpoint specifico dell’API a cui si desidera accedere

Esempi:

https://public-api.wordpress.com/rest/v1.4/me
https://public-api.wordpress.com/wpcom/v4/notifications
https://public-api.wordpress.com/wp/v2/posts

Struttura URL specifica per sito

Quando si accede a endpoint che operano su siti WordPress.com specifici, la struttura dell’URL include un identificatore del sito:

https://public-api.wordpress.com/{namespace}/{version}/sites/{site_id}/{endpoint}

Parametri:

• {namespace}: Il namespace dell’API (ad es. ‘rest’, ‘wp’, ‘wpcom’)
• {version}: La versione dell’API (ad es. ‘v1’, ‘v1.4’, ‘v2’, ‘v4’)
• {site_id}: L’identificatore numerico univoco del sito WordPress.com
• {endpoint}: L’endpoint specifico relativo al sito (ad es. ‘posts’, ‘pages’, ‘media’, ‘users’)

Esempi:

https://public-api.wordpress.com/wp/v2/sites/241031857/posts
https://public-api.wordpress.com/rest/v1.4/sites/241031857/stats
https://public-api.wordpress.com/wpcom/v2/sites/241031857/follows

Ottenere l’ID del sito

Per utilizzare gli endpoint specifici del sito, è necessario ottenere l’identificativo numerico univoco del proprio sito. Puoi ottenere questa informazione effettuando una richiesta all’endpoint /rest/v1.1/me/sites dalla Console API:

1. Visita la Console API di WordPress.com
2. Naviga all’endpoint /rest/v1.1/me/sites (che si trova in WP.COM API - v1.1/me/sites nella Console)
3. Esegui la richiesta per recuperare tutti i siti associati al tuo account
4. Individua il campo ID nella risposta per il sito desiderato

L’endpoint /rest/v1.1/me/sites restituisce informazioni dettagliate su tutti i siti associati al tuo account WordPress.com, tra cui:

• ID: l’identificativo numerico univoco del sito (quello necessario per le chiamate API)
• name: il nome visualizzato del sito
• URL: l’URL pubblico del sito
• jetpack: indica se il sito è un sito connesso tramite Jetpack
• is_private: indica se il sito è privato
• capabilities: le azioni che puoi eseguire sul sito

Esempio di risposta:

{
  "sites": [
    {
      "ID": 241031857,
      "name": "My Blog",
      "URL": "https://myblog.wordpress.com",
      "jetpack": false,
      "is_private": false,
      "capabilities": {
        "edit_posts": true,
        "publish_posts": true
      }
    }
  ]
}

Formati URL alternativi

Potresti incontrare alcuni formati URL alternativi:

• Accesso diretto al sito, come https://yoursite.com/wp-json/wp/v2/posts – Questo formato funziona solo per siti self-hosted con Jetpack. Potrebbe non funzionare a causa di impostazioni di sicurezza, regole del firewall o problemi di autenticazione.
• Accesso a WordPress.com basato sul dominio, come https://public-api.wordpress.com/wp/v2/sites/yoursite.com/posts – Questo formato non è affidabile per siti con domini personalizzati, configurazioni DNS o quando i domini cambiano.

Per evitare qualsiasi problema, l’approccio consigliato è utilizzare il formato con ID numerici del sito, che è più affidabile, più veloce, funziona in modo coerente su tutti i tipi di sito e supporta tutte le funzionalità e i metodi di autenticazione di WordPress.com.

Requisiti di autenticazione

La REST API di WordPress.com supporta sia richieste autenticate che non autenticate, a seconda dell’endpoint e dei dati a cui stai cercando di accedere. Comprendere quando e come autenticarsi è fondamentale per un’integrazione API di successo.

Le richieste non autenticate funzionano per:

• Informazioni pubbliche del sito (ad es., dettagli del sito, articoli pubblici)
• Lettura di contenuti pubblici da siti WordPress.com
• Accesso a statistiche e dati disponibili pubblicamente

Esempi di richieste non autenticate:

# Get public information about a site
curl https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/

# Get public posts from a site
curl https://public-api.wordpress.com/wp/v2/sites/en.blog.wordpress.com/posts?per_page=5

L’autenticazione è richiesta per:

• Creazione, modifica o eliminazione di contenuti (articoli, pagine, commenti)
• Accesso a siti privati o contenuti privati
• Gestione delle impostazioni e della configurazione del sito
• Accesso a dati specifici dell’utente (notifiche, siti seguiti, statistiche personali)
• Qualsiasi operazione che richiederebbe all’utente di essere connesso quando utilizza direttamente WordPress.com

Esempi di richieste autenticate (richiedono un token):

# Get your user profile (requires authentication)
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
     https://public-api.wordpress.com/rest/v1.4/me

# Create a new post (requires authentication)
curl -X POST 
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
     -H "Content-Type: application/json" 
     -d '{"title":"My New Post","content":"This is the post content","status":"publish"}' 
     https://public-api.wordpress.com/wp/v2/sites/YOUR_SITE_ID/posts

# Get your site's stats (requires authentication)
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
     https://public-api.wordpress.com/rest/v1.4/sites/YOUR_SITE_ID/stats

Metodi di autenticazione

Tutta l’autenticazione della REST API di WordPress.com è basata su token. Ogni richiesta autenticata richiede un token di accesso OAuth2 ottenuto dagli endpoint OAuth2 di WordPress.com. I metodi più rilevanti per ottenere questi token sono:

• Scambio diretto di credenziali per token (per uso personale e sviluppo)
• Flusso OAuth2 completo (consigliato per applicazioni di terze parti)

Scambio diretto di credenziali per token

Le password per applicazioni offrono una scorciatoia per ottenere token di accesso OAuth2 senza implementare il flusso completo di autorizzazione utente. Questo metodo utilizza il flusso OAuth2 grant_type=password per scambiare direttamente il nome utente WordPress.com e la password per applicazioni con un token di accesso.

Quando utilizzare questo metodo:

• Progetti personali e sviluppo
• Strumenti e script da riga di comando
• Applicazioni che accedono solo ai tuoi siti WordPress.com
• Test e prototipazione

Come funziona: Invece di reindirizzare gli utenti attraverso l’interfaccia di autorizzazione di WordPress.com, utilizzi la tua Password per Applicazioni per richiedere direttamente un token dall’endpoint OAuth2. Questo bypassa il passaggio di consenso dell’utente ma richiede le tue credenziali WordPress.com effettive.

Come utilizzare lo scambio diretto di token tramite credenziali:

Per utilizzare questo metodo, dovrai:

• Creare una nuova applicazione WordPress.com per ottenere il Client ID e il Client Secret della tua app.
• Se hai l’autenticazione a due fattori abilitata (fortemente consigliata), crea una nuova Password per Applicazioni. Altrimenti, utilizza la tua password abituale.

Questo metodo utilizza il flusso OAuth2 grant_type=password per scambiare direttamente la tua Password per Applicazioni con un token di accesso:

# Step 1: Generate an OAuth2 access token using your Application Password
curl -X POST "https://public-api.wordpress.com/oauth2/token" 
  -d "client_id=<CLIENT_ID>" 
  -d "client_secret=<CLIENT_SECRET>" 
  -d "grant_type=password" 
  -d "username=<USERNAME>" 
  -d "password=<APPLICATION_PASSWORD>"


# Response will contain your access token:
# {
#   "access_token": "your_oauth2_token_here",
#   "token_type": "bearer",
#   "scope": "global"
# }

# Step 2: Use the OAuth2 token for all API requests
curl -X GET 
  'https://public-api.wordpress.com/rest/v1.1/sites/YOUR_SITE_ID/posts' 
  -H 'Authorization: Bearer your_oauth2_token_here' 
  -H 'Content-Type: application/json'

# Create a post using the token
curl -X POST 
  'https://public-api.wordpress.com/wp/v2/sites/YOUR_SITE_ID/posts' 
  -H 'Authorization: Bearer your_oauth2_token_here' 
  -H 'Content-Type: application/json' 
  -d '{"title":"My New Post","content":"Post content here","status":"publish"}'

Punti chiave:

• Le Password per Applicazioni non vengono mai utilizzate direttamente con gli endpoint di public-api.wordpress.com
• Vengono utilizzate solo con l’endpoint token OAuth2 per ottenere i token di accesso
• Il token risultante è identico ai token ottenuti tramite il flusso OAuth2 completo
• Tutte le successive richieste API utilizzano il token OAuth2, non la Password per Applicazioni

Flusso OAuth2 completo

Il flusso OAuth2 completo è l’approccio consigliato per le applicazioni di terze parti che necessitano che gli utenti autorizzino l’accesso ai propri siti e dati WordPress.com. Questo metodo fornisce il sistema di permessi più sicuro e granulare.

Quando utilizzare questo metodo:

• Applicazioni di terze parti che accedono ai dati degli utenti
• Applicazioni web con più utenti
• Applicazioni mobile
• Qualsiasi app che necessita di permessi controllati dall’utente

Come funziona: Gli utenti vengono reindirizzati su WordPress.com dove possono esaminare e autorizzare i permessi specifici richiesti dalla tua applicazione. Dopo l’autorizzazione, la tua applicazione riceve un token di accesso che può essere utilizzato per effettuare richieste API per conto dell’utente.

Riepilogo del flusso OAuth2 completo:

1. Registra la tua applicazione su WordPress.com Apps per ottenere il tuo client ID e il secret
2. Reindirizza gli utenti all’URL di autorizzazione di WordPress.com con il tuo client ID e gli scope richiesti
3. L’utente esamina e concede il permesso tramite l’interfaccia di WordPress.com
4. WordPress.com reindirizza alla tua app con un codice di autorizzazione
5. Scambia il codice di autorizzazione con un token di accesso OAuth2 utilizzando il tuo client secret
6. Utilizza il token di accesso OAuth2 in tutte le richieste API con Authorization: Bearer YOUR_TOKEN

Il risultato è lo stesso formato di token di accesso OAuth2 utilizzato dal metodo Credentials Direct Token Exchange, garantendo un’autenticazione coerente tra entrambi gli approcci.

Per una guida dettagliata sull’implementazione di OAuth2, inclusi esempi di codice e considerazioni sulla sicurezza, consulta la documentazione OAuth2 Authentication.

Risoluzione dei problemi di autenticazione e best practice

Errori di autenticazione comuni

401 Unauthorized

• Causa: Token di accesso non valido o mancante
• Soluzione: Verifica che il token sia corretto e incluso nell’header Authorization

403 Forbidden

• Causa: Token valido ma permessi insufficienti per l’azione richiesta
• Soluzione: Verifica che il tuo account utente disponga delle capacità necessarie per il sito

Formato del token non valido

• Causa: Formato dell’header non corretto
• Soluzione: Assicurati di utilizzare Authorization: Bearer YOUR_TOKEN (nota lo spazio dopo “Bearer”)

Best practice di sicurezza

1. Non esporre mai le credenziali nel codice lato client – Le password per applicazioni devono essere utilizzate solo in applicazioni lato server
2. Utilizza variabili d’ambiente – Memorizza nomi utente e password in variabili d’ambiente, non nel codice sorgente
3. Ruota le password regolarmente – Genera periodicamente nuove password per applicazioni e revoca quelle vecchie
4. Utilizza OAuth2 per le app rivolte agli utenti – Non utilizzare le password per applicazioni per applicazioni con cui altri utenti dovranno autenticarsi
5. Comprendi il sistema di token unificato – Entrambi i metodi di autenticazione generano gli stessi token di accesso OAuth2, garantendo un accesso API e una sicurezza coerenti
6. Scegli il metodo giusto – Utilizza la scorciatoia Password per applicazioni per uso personale/sviluppo, il flusso OAuth2 completo per applicazioni di terze parti
7. Gestione dei token – I token possono essere revocati per singola applicazione senza influire sulle altre app, offrendo una sicurezza migliore rispetto alla condivisione delle password

Applicazioni basate su browser

Se stai sviluppando un’applicazione basata su browser, dovrai:

1. Usa il flusso implicito OAuth2 – Le password dell’applicazione non devono essere utilizzate nel codice lato client
2. Inserisci i tuoi domini nella whitelist – Configura le origini consentite nelle impostazioni dell’app WordPress.com
3. Gestisci correttamente il CORS – L’API invierà le intestazioni CORS appropriate per i domini nella whitelist

Per indicazioni dettagliate sulle implementazioni basate su browser, consulta Usare la REST API da JS e dal browser.

Risorse e documentazione

• Console API – Test interattivo ed esplorazione
• Riferimento API – Documentazione completa degli endpoint
• WordPress REST API Handbook – Documentazione ufficiale della REST API del core di WordPress
• Blog per sviluppatori – Aggiornamenti e annunci sulle modifiche all’API