Namespace e versioni

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

La REST API di WordPress.com è organizzata in tre namespace distinti, ciascuno con scopi specifici e schemi di versionamento indipendenti. Comprendere questi namespace è essenziale per scegliere gli endpoint giusti per la propria integrazione e garantire la compatibilità sia con WordPress.com che con i siti WordPress self-hosted.

Panoramica dei namespace API

La REST API di WordPress.com fornisce tre namespace principali, ciascuno destinato a casi d’uso e livelli di compatibilità differenti:

Namespace	Versioni disponibili	Scopo principale	Compatibile con WordPress Core
/rest/	v1, v1.1, v1.2, v1.3, v1.4	Gestione legacy di WordPress.com e funzionalità della piattaforma	No
/wp/	v2	Risorse standard di WordPress core conformi alla specifica ufficiale della REST API	Sì
/wpcom/	v2, v3, v4	Funzionalità e servizi moderni specifici di WordPress.com	No

Namespace /rest/ – API legacy di WordPress.com

Il namespace /rest/ rappresenta la REST API originale di WordPress.com, precedente alla REST API di WordPress core. Fornisce un accesso completo alle funzionalità della piattaforma WordPress.com e alle capacità di gestione dei siti.

Versioni disponibili: v1, v1.1, v1.2, v1.3, v1.4 (accessibili tramite l’opzione WP.COM API nella Console API)

URL di base:

• https://public-api.wordpress.com/rest/v1/
• https://public-api.wordpress.com/rest/v1.1/
• https://public-api.wordpress.com/rest/v1.2/
• https://public-api.wordpress.com/rest/v1.3/
• https://public-api.wordpress.com/rest/v1.4/

Funzionalità principali:

• Gestione completa di siti e utenti
• Funzionalità specifiche di WordPress.com come Statistiche, Reader e notifiche
• Configurazione avanzata del sito e gestione dei domini
• Funzionalità di integrazione con Jetpack

Strategia di versionamento: Ogni versione (v1.1–v1.4) ha introdotto miglioramenti incrementali, nuovi endpoint e funzionalità avanzate, mantenendo la compatibilità con le versioni precedenti. Quando gli endpoint esistono in più versioni, le versioni più recenti offrono generalmente campi aggiuntivi, prestazioni migliorate o correzioni di bug.

Ideale per:

• Accedere a funzionalità specifiche di WordPress.com non disponibili altrove
• Gestione e configurazione avanzata del sito
• Mantenere la compatibilità con le integrazioni esistenti
• Funzionalità come statistiche dettagliate, funzionalità del Reader e gestione dei domini

Endpoint di esempio:

• /rest/v1.4/sites/{site}/posts
• /rest/v1.4/sites/{site}/stats
• /rest/v1.4/me/sites
• /rest/v1.3/read/following

Namespace /wp/ – WordPress Core REST API

Il namespace /wp/ implementa la specifica ufficiale della WordPress REST API, garantendo piena compatibilità sia con WordPress.com che con i siti WordPress self-hosted. Questo namespace segue gli standard stabiliti dal team core di WordPress.

Versione disponibile: v2 (accessibile tramite l’opzione WP REST API nella Console API)

URL di base: https://public-api.wordpress.com/wp/v2/

Funzionalità principali:

• Risorse WordPress standard (articoli, pagine, commenti, tassonomie, utenti, media)
• Piena compatibilità con i siti WordPress self-hosted
• Struttura degli endpoint coerente, conforme agli standard del core di WordPress
• Estensibile tramite plugin sui siti self-hosted

Filosofia di design: Questo namespace privilegia la standardizzazione e la compatibilità rispetto alle funzionalità specifiche di WordPress.com. Rispecchia la REST API disponibile su qualsiasi installazione WordPress, rendendolo ideale per le applicazioni che devono funzionare in diversi ambienti WordPress.

Ideale per:

• Nuovi progetti che richiedono le funzionalità del core di WordPress
• Applicazioni che devono funzionare sia con WordPress.com che con siti self-hosted
• Gestione standard dei contenuti (articoli, pagine, media, utenti)
• Integrazioni con strumenti e plugin WordPress esistenti

Endpoint di esempio:

• /wp/v2/posts
• /wp/v2/pages
• /wp/v2/users
• /wp/v2/media
• /wp/v2/sites/{site}/posts

Namespace /wpcom/ – API moderna della piattaforma WordPress.com

Il namespace /wpcom/ rappresenta l’evoluzione delle funzionalità API specifiche di WordPress.com, con pattern di design moderno e funzionalità avanzate della piattaforma non disponibili nel core di WordPress.

Versioni disponibili: v2, v3, v4 (accessibili tramite l’opzione WP REST API nella Console API)

URL di base:

• https://public-api.wordpress.com/wpcom/v2/
• https://public-api.wordpress.com/wpcom/v3/
• https://public-api.wordpress.com/wpcom/v4/

Funzionalità principali:

• Design moderno dell’API con struttura e prestazioni migliorate
• Servizi avanzati di WordPress.com (Reader, Statistiche avanzate, notifiche)
• Funzionalità di coinvolgimento degli utenti (follow, like, raccomandazioni)
• Funzionalità specifiche della piattaforma non disponibili in WordPress self-hosted

Strategia di versionamento: ogni versione introduce nuove capacità, miglioramenti della sicurezza e strutture dati perfezionate. A differenza del namespace /rest/, /wpcom/ si concentra su funzionalità orientate al futuro piuttosto che sulla compatibilità con versioni precedenti.

Ideale per:

• Funzionalità moderne della piattaforma WordPress.com
• Funzionalità di coinvolgimento degli utenti e social
• Analisi avanzate e raccomandazioni
• Nuove integrazioni che richiedono le più recenti funzionalità di WordPress.com

Endpoint di esempio:

• /wpcom/v4/me/follows
• /wpcom/v3/notifications
• /wpcom/v2/read/tags
• /wpcom/v4/sites/{site}/stats/insights

Scegliere il namespace giusto

La scelta del namespace dipende dai requisiti specifici e dalle esigenze di compatibilità:

Usa /wp/v2/ quando hai bisogno delle funzionalità standard di WordPress come:

• Funzionalità core di WordPress (articoli, pagine, utenti, media)
• Compatibilità con siti WordPress self-hosted
• Pattern e strutture standard della REST API
• Integrazione con strumenti e plugin WordPress esistenti

Usa /wpcom/v4/ (o l’ultima versione disponibile) quando hai bisogno delle funzionalità della piattaforma WordPress.com come:

• Servizi avanzati di WordPress.com e funzionalità social
• Design moderno delle API e prestazioni migliorate
• Ultime funzionalità e integrazioni della piattaforma
• Funzionalità esclusive dell’ecosistema WordPress.com

Usa /rest/v1.4/ (o la versione richiesta) quando hai bisogno di funzionalità legacy e compatibilità come:

• Funzionalità specifiche disponibili solo negli endpoint legacy
• Retrocompatibilità con integrazioni esistenti
• Funzionalità avanzate di gestione del sito non ancora migrate ai namespace più recenti
• Funzionalità complete di statistiche e analisi

Linee guida per la selezione della versione

All’interno di ciascun namespace, la selezione della versione segue questi principi:

Versioni multiple disponibili: Quando gli endpoint esistono in più versioni, le versioni più recenti offrono generalmente:

• Campi di risposta e parametri aggiuntivi
• Prestazioni e affidabilità migliorate
• Correzioni di bug e miglioramenti della sicurezza
• Funzionalità avanzate mantenendo la compatibilità con le versioni precedenti

Approccio consigliato: Utilizzare sempre l’ultima versione disponibile, a meno che:

• La propria integrazione dipenda da un comportamento specifico delle versioni precedenti
• Si stia mantenendo codice legacy che richiede risposte API specifiche
• Requisiti di compatibilità impongano una versione particolare

Comprendere l’organizzazione della console API

La console API di WordPress.com organizza i namespace in due categorie principali:

• WP.COM API: Contiene tutte le versioni del namespace /rest/ (v1–v1.4)
• WP REST API: Contiene /wp/v2/ e tutte le versioni del namespace /wpcom/ (v2–v4)

Questa organizzazione riflette l’evoluzione dalle API specifiche di WordPress.com alle API standardizzate del core di WordPress e alle funzionalità moderne della piattaforma.

Considerazioni sulla migrazione

Quando si pianificano integrazioni o si aggiornano quelle esistenti:

Nuovi progetti: Inizia con /wp/v2/ per le funzionalità principali e /wpcom/v4/ per le funzionalità specifiche della piattaforma.

Integrazioni esistenti: Valuta la migrazione dagli endpoint /rest/ ai namespace più recenti quando:

• Funzionalità equivalenti sono disponibili in /wp/v2/ o /wpcom/
• Hai bisogno di prestazioni migliori o funzionalità aggiuntive
• La manutenzione e il supporto a lungo termine sono prioritari

Disponibilità delle funzionalità: Alcune funzionalità avanzate rimangono esclusive del namespace /rest/. Valuta i requisiti funzionali prima della migrazione per assicurarti che tutte le funzionalità necessarie siano disponibili nei namespace di destinazione.