3. díl: WordPress REST API – tvoříme aplikaci na publikování příspěvků

Úplným začátečníkům, kteří s REST API ještě nepracovali, doporučujeme přečíst si nejprve předchozí části našeho seriálu. V prvním díle WordPress REST API – co umí a jak ho můžete využít i vy  se dozvíte, jaké nové možnosti API ve světě WordPressu přineslo. Druhý díl nese název Jak pracovat s REST API ve WordPressu? Návod pro začátečníky a naučíte se v něm základní pojmy a operace. A teď už přejděme navrhování aplikace.

Představme si, že chceme vytvořit aplikaci, která bude mít za úkol připojit se k žádanému webu, kde běží WordPress, a zobrazit z něj dosud nepublikované příspěvky. Umožní nám zobrazit každý takový příspěvek a eventuálně jej publikovat. Kromě toho aplikace umožní zařadit příspěvek do kategorií či mu přidělí štítky.

1. Autentizace

Jelikož budeme potřebovat na webu skrze naši aplikaci provádět změny a zobrazovat nepublikované příspěvky, budeme se muset vůči webu autentizovat. Více o těchto možnostech diskutuje téma dokumentace Authentication. Pro testovací účely můžeme využít basic authentication, což znamená, že v každém požadavku na REST API budeme posílat naše přihlašovací údaje.

2. Ověření WordPress webu a základní adresa API

Po vyřešení autentizace je naše aplikace připravena komunikovat s webem. Nejdříve potřebujeme ověřit, zda se na zadané adrese webu nachází WordPress a jaká je základní adresa jeho API. To učiníme tak, že pošleme na adresu webu HTTP požadavek metodou HEAD.

HEAD http://www.example.com

(Pozn. Vzorovou doménu example.com nahraďte vlastní doménou).

Pokud na dané adrese skutečně běží WordPress, obdržíme v hlavičkách odpovědi pole link, který obsahuje následující:

Link: <http://www.example.com/wp-json/>; rel=https://api.w.org/

To říká, že vztah (rel) “https://api.w.org/“ (URI pro WordPress REST API) ukazuje na http://www.example.com/wp-json/. Všechny naše další požadavky, které bude posílat naše aplikace, budou vycházet z tohoto bodu.

Pro pořádek bychom v tuto chvíli měli pro jistotu ještě na základní endpoint API poslat HTTP požadavek metodou GET a ujistit se, že v odpovědi pod klíčem “namespaces” je v seznamu uveden i jmenný prostor “wp/v2“, v němž se nacházejí všechny endpointy, pomocí kterých budeme web ovládat. Více o průzkumu API hovoří téma dokumentace Discovery.

3. Získání seznamu příspěvků

Pokud se nám podařilo ujistit, že si s webem, ke kterému se chceme připojit, budeme rozumět, můžeme přikročit k získání seznamu příspěvků. Na základě dříve získaných informací a jejich ověření dokážeme sestavit endpoint pro získání příspěvků, který v tomto případě je:

GET http://www.example.com/wp-json/wp/v2/posts

Tím ovšem získáme seznam 10 nejnovějších, již publikovaných příspěvků. Abychom získali větší seznam, řekněme 50 příspěvků, které čekají na publikování, musíme endpointu přidat příslušné parametry metody GET dle tématu dokumentace List Post takto:

GET http://www.example.com/wp-json/wp/v2/posts?status=pending&per_page=50

Odpovědí nám je kolekce objektů příspěvků ve formátu JSON, tedy sada vlastností příspěvku uzavřená ve složených závorkách {} a celá kolekce uzavřená v hranatých závorkách []. Například:

[
	{
		"id":31,
		"modified":"2018-11-21T11:31:05",
		"title":{
			"rendered":"My first post"
			},
		...
	},
	{
		"id":32,
		"modified":"2018-11-21T11:32:33",
		"title":{
			"rendered":"My second post"
			},
		...
	},
	...
]

V naší aplikaci budeme chtít v seznamu u každého příspěvku zobrazit jeho název, jméno autora a datum poslední úpravy. K tomu si navíc musíme zapamatovat ke každému příspěvku jeho ID, které budeme potřebovat v dalších požadavcích.

Pokud odpověď blíže prozkoumáme, zjistíme, že jméno autora je u příspěvku uvedeno jen pomocí jeho ID. Sekce “links” ovšem navíc obsahuje vztah typu “author” ukazující na endpoint, který poskytuje informace o autorovi příspěvku a k tomu atribut “embeddable” nastavený na “true”. To znamená, že pokud chceme, mohou být informace o autorovi zahrnuty do odpovědi bez toho, abychom museli na API pokládat další požadavek. Parametry u diskutovaného endpointu tedy ještě trochu upravíme:

GET http://www.example.com/wp-json/wp/v2/posts?status=pending&per_page=50&_embed

Parametr _embed způsobí, že všechny objekty ze vztahu majících atribut “embeddable” s hodnotou “true” budou zahrnuty přímo do odpovědi, konkrétně u každého příspěvku do sekce “_embedded”. Názvy klíčů v této sekci odpovídají názvům vztahů uvedených v sekci “_links”.

Vložené objekty nemusí mít na tomto místě uvedeny všechny své vlastnosti, což je dáno použitým kontextem embed. WordPress totiž rozlišuje tři kontexty (výchozí view, edit či embed), v nichž objekty jako jsou příspěvky, uživatelé či kategorie, mohou být prezentovány.

Na to, jak může ve formátu JSON vypadat jedna položka v odpovědi se seznamem příspěvků, se můžete podívat v příkladu.

Pro vypsání seznamu příspěvků v naší aplikaci potřebujeme z každého objektu příspěvků tyto vlastnosti:

• “id” – ID příspěvku.
• “title”.“rendered” – Název příspěvku. Používáme podvlastnost “rendered” objektu „title“, v níž je uveden název již naformátovaný k zobrazení. Zobrazení názvu příspěvku mohou ovlivnit aktivní doplňky a šablona webu (viz filtr “the_title”).
• “modified” – Čas poslední změny podle normy ISO 8601, který si musíme ještě přeformátovat do čitelnějšího formátu.
• “_embedded”.”author”[0].”name” – Jméno autora, které je uvedeno ve vlastnosti „name“ prvního a jediného objektu, jenž se nachází v poli podvlastnosti „“_embedded”.”author”.

Když uživatel klikne na příspěvek, zobrazí se v naší aplikaci jeho detail. Kromě tedy již zobrazených informací o názvu, datu poslední změny a jména autora si přejeme zobrazit jeho obsah. Ten v odpovědi s kolekcí není ale uveden, neboť příspěvky se do kolekce uvádějí v kontextu typu embed, proto musíme poslat požadavek na endpoint, kde získáme detail příspěvku včetně jeho obsahu. Tvar endpointu dle tématu dokumentace Retrieve a Post pro náš web bude:

GET http://www.example.com/wp-json/wp/v2/posts/<id>

<id> je ID příspěvku, jehož detail chceme získat. V odpovědi potom pod vlastností “content”.”rendered” nalezneme HTML kód obsahu příspěvku, který prošel filtrem the_content a můžeme jej tak ihned zobrazit.

4. Zobrazení kategorií a štítků

Abychom mohli zobrazit i kategorie a štítky přiřazené k příspěvku, je opět výhodné použít parametr _embed, např. pro příspěvek s ID 123 dáme požadavek na endpoint:

GET http://www.example.com/wp-json/wp/v2/posts/123?_embed

Kategorie jsou uvedené ve výčtu pod vlastností “categories” a štítky pod vlastností “tags”. V těchto výčtech jsou uvedeny jen ID termů, které musíme spárovat s objekty termů, které se nacházejí v kolekci pod vlastností “_embedded”.”wp:term”[0] a až potom u každého termu můžeme vypsat jeho název z vlastnosti “name”.

5. Publikování příspěvků

Již dříve jsme řekli, že naše aplikace bude umět editovat kategorie a štítky a přepnout status příspěvku z pending na publish. Co se týče publikování, vystačíme si s jediným požadavkem na stejný endpoint jako v případě získávání detailu, jen namísto metody GET použijeme POST. V těle požadavku musíme uvést, které vlastnosti příspěvku chceme změnit. Konkrétně např. pro publikování příspěvku s ID 123 provedeme požadavek:

POST http://www.example.com/wp-json/wp/v2/posts/123
{"status":"publish"}

Pokud změna statusu proběhne v pořádku, měla by naší aplikaci přijít zpět odpověď s informacemi o příspěvku, tentokrát v kontextu typu edit, přičemž pod vlastností “status” by již měla být hodnota “publish”.

6. Změna kategorií a štítků

Co se týče změny kategorií a štítků, budeme postupovat podobně, jen v těle požadavku uvedeme nové výčty kategorií a štítků, např. opět pro náš příspěvek s id 123:

POST http://www.example.com/wp-json/wp/v2/posts/123
{ 
"categories":[2,4],
"tags":[3,5,6]
}

Čímž říkáme, že příspěvek má patřit do kategorií s ID 2 a 4 a pod štítky s ID 3, 5 a 6. Staré výčty kategorií a štítků se přepíší a nahradí novými.

7. Uživatelská přívětivost

To je pozadí této operace, samozřejmě pro uživatele musí naše aplikace vytvořit rozhraní přívětivé, prosté zadávání jakýchkoli ID. Nechceme-li si práci příliš komplikovat, vystačíme si již s kategoriemi a štítky, které na webu jsou již vytvořeny. Samozřejmě pomocí příslušných endpointů ale můžeme vytvářet kategorie a štítky nové, stačí prostudovat téma Create a Category či Create a Tag. Aby si uživatel naší aplikace mohl vybrat ze seznamu kategorií a štítků, musíme získat jejich kolekce termů. Pro kategorie je to na našem webu endpoint http://www.example.com/wp-json/wp/v2/categories a pro štítky http://www.example.com/wp-json/wp/v2/tags. Samozřejmě pro získání použijeme HTTP metodu GET, přičemž obdržíme v obou případech odpověď podobného formátu, protože jak kategorie, tak štítky jsou taxonomie.

Z každého objektu termu pro vypsání nám postačují vlastnosti “id” a “name”. Při vypisování seznamů zaznačíme v naší aplikaci kategorii či štítek, který je již k příspěvku přiřazen (vlastnosti “categories” a “tags” v odpovědi s detailem příspěvku). Až uživatel v naší aplikaci zaznačí a odznačí všechny kategorie a štítky tak, jak si přeje, posbíráme seznam zaznačených kategorií a zaznačených štítků a provedeme výše diskutovaný požadavek (v sekci 6. změna kategorií a štítků).

Podařilo se vám aplikaci vytvořit? Narazili jste na problém? Napište nám a my vám rádi pomůžeme. Náš seriál tímto dílem nekončí – připravujeme pro vás další článek s praktickými radami, jak dále REST API ve WordPressu využít.