2. díl: Jak pracovat s REST API ve WordPressu? Návod pro začátečníky

Pokud se s REST API teprve seznamujete a chcete s ním začít pracovat, jste tady správně. V článku vám představíme nejdůležitější pojmy REST API a krok za krokem vás provedeme prvními operacemi.

Více informací o možnostech a významu REST API najdete v úvodním článku seriálu WordPress REST API – co umí a jak ho můžete využít i vy. Pokud prahnete po pokročilejších informacích a návodech, přečtěte si navazující díl, ve kterém vám ukážeme, jak s pomocí REST API vytvořit aplikaci k publikování a kategorizování nevydaných příspěvků.

Začínáme s Postmanem

Abyste si vyzkoušeli práci s REST API, potřebujete v prvé řadě instalaci WordPressu, což zahrnuje mít webhosting s PHP nebo nakonfigurovaný lokální webový server a na něj nahranou instalaci WordPressu. Více o instalaci se dozvíte v oficiální příručce WordPressu. Pro plné využití WordPress REST API potřebujete WordPress verzi 4.7 a novější.

Pro testovací účely a vyzkoušení komunikace s REST API je kromě toho nutné nainstalovat si HTTP klienta, který vám umožní zasílat požadavky serveru a zobrazovat jeho odpovědi. Takovým klientem může být aplikace Postman. Postman umožňuje jednoduchým způsobem vyzkoušet, jak má požadavek na server vypadat. Uživatel určí metodu a endpoint, tělo požadavku, připojí autentizační údaje a vše odešle. Vzápětí mu od serveru přijde odpověď. Jako testovací server můžete použít URL https://postman-echo.com, kde najdete i pár testovacích příkazů.

V reálném projektu vám ale Postman stačit nebude, je třeba pracovat s knihovnami pro komunikaci skrze protokol HTTP, například v PHP je to knihovna cURL (příklad s cURL najdete na konci článku).

Hlavní pojmy na začátek

Autentizace

Zásadním pojmem v REST API je autentizace, bez ní nemůžete začít pracovat. Jednoduše řečeno – autentizace je prokázání se určitému serveru, že jste oprávněnou osobou k zasílání požadavků. Jakmile svou totožnost prokážete, nic vám nebude bránit v mazání příspěvků nebo získávání dat o uživatelích, proto je nutné se autentizovat před každým použitím programu.

REST API nabízí hned několik možností autentizace, každý typ se hodí pro jiné příležitosti. Autentizace je téma, které by vydalo na samostatný článek, proto zde uvádíme jen základní přehled možností. Více konkrétnějších informací o tom, jak na autentizaci, i možnosti konkrétních pluginů pro WordPress, najdete v oficiální příručce v sekci Autentizace.

• Basic authentication odesílá v hlavičce požadavku jméno a heslo uživatele. Není ale bezpečná a hodí se pouze pro testovací účely.
• Další varianta je obdobně založená na basic authentication (tzv. application password), ale místo jména a hesla využívá klíč vygenerovaný serverem, který se zadá do klienta. K tomu je zapotřebí doplňku pro WordPress.
• Autentizace skrze cookies se využívá pro komunikaci v JavaScriptu v rámci WordPressu mezi rozhraním v prohlížeči a serverem.
• Nejsofistikovanějším způsobem je OAuth autentizace. Využívají ji různé služby (Google, Twitter), uživatel se serveru prokáže mimo aplikaci, je mu propůjčen klíč a on ho potom používá k přihlašování.

V aplikaci Postman najdete jednotlivé formy autentizace pod jinými názvy. Více o autentizaci v Postmanu se můžete dočíst zde.

Protokol HTTP a CRUD operace

Komunikace v aplikaci probíhá přes protokol HTTP, který je založený na tom, že naše aplikace zformuluje požadavek a odešle ho na WordPress server, kde je API nainstalované. Adresa, na kterou je požadavek směřován, se nazývá endpoint (o tom více později).

REST API umožňuje provádět tzv. CRUD operace. Jedná se o omezený soubor HTTP příkazů s jasně definovaným významem, mezi které patří následující:

• GET – čtení nebo získání objektu
• POST – vytvoření nového objektu
• PUT – aktualizování objektu
• DELETE – smazání objektu
• HEAD – kontrolování zda objekt existuje
• OPTIONS – získání všech podporovaných příkazů

První čtyři metody jsou součástí zmiňovaných CRUD akcí, poslední dva požadavky pomáhají klientovi v určení toho, zda zdroj existuje, a které HTTP požadavky je možné použít pro provedení dalších operací.

HTTP odpovědi

Server, na kterém je nainstalovaný WordPress, reaguje na požadavek vrácením odpovědi, která obsahuje stavový kód HTTP a data ve formátu JSON. Stavové kódy jsou tvořeny čísly s předdefinovanými významy. Všichni uživatelé webu budou jistě znát stavový kód 404, který oznamuje, že zdroj, po kterém uživatel pátrá, nebyl nalezen. Odpověď serveru je závislá na HTTP požadavku nebo na metodě, kterou jsme použili v požadavku.

Endpoint a route

Už výše jsme zmínili, že endpoint je v podstatě adresa, na kterou zasíláme požadavky, zároveň má endpoint sám o sobě vlastní parametry.

Endpointy jsou funkce, dostupné skrze API, které provádí několik akcí, jakými jsou například získávání příspěvků nebo vytvoření nového uživatele. Mohli bychom říci, že endpoint spouští proceduru, která provádí určitý úkol. Tyto endpointy jsou závislé na předaných parametrech.

Například můžeme využít metodu GET k získání všech příspěvků: GET http://localserver/wp-json/wp/v2/posts (případně testovací url z postman-echo GET https://postman-echo.com/get?foo1=bar1&foo2=bar2).

Příklad využití metody GET

A tady se dostáváme k dalšímu zásadnímu pojmu. Route (cesta) pro výše zmíněný endpoint je wp/v2/posts. Route je cesta pro přístup k endpointu. Jedna route může mít vícero endpointů podle toho, jaký je použit HTTP požadavek. Výše zmíněná route má následující endpoint pro vytvoření nového příspěvku POST wp/v2/posts. Tento endpoint spuštěný doplněnými parametry vytvoří nový příspěvek.

Abychom si v tom udělali jasno, představme si následující route wp/ v2/posts/100. Tato route se vztahuje k příspěvku s ID 100. Má následující tři endpointy:

1. GET wp/v2/posts/100                  Slouží k získání příspěvku s ID 100.
2. PUT wp/v2/posts/100                  Slouží k aktualizaci příspěvku s ID 100.
3. DELETE wp/v2/posts/100               Slouží ke smazání příspěvku s ID 100.

Praktické příklady

Získání příspěvku

Pro získání dat ze serveru využíváme metodu GET. Jakmile server požadavek přijme, doručí klientovi kolekci všech objektů příspěvků ve formátu JSON. Chceme-li získat příspěvek, náš požadavek bude vypadat takto:

GET http://localserver/wp-json/wp/v2/posts
HOST: localserver

Můžeme také získat konkrétní příspěvek zmíněním jeho ID (v tomto případě ID 100):

GET http://localserver/wp-json/wp/v2/posts/100

Chceme-li najít příspěvek splňující specifická kritéria, využijeme parametr filter[] (v tomto případě získáme všechny příspěvky spadající do kategorie ID 1):

GET http://localserver/wp-json/wp/v2/posts?filter[cat]=1 

Vytvoření nového příspěvku

K vytvoření nového příspěvku se využívá metoda POST, která musí zahrnovat v hlavičkách pole content-type (text/xml nebo application/xml, pokud posíláte data ve formátu xml, nebo application/json, pokud posíláte data ve formátu JSON). Po hlavičkách následuje tělo požadavku s daty ve formátu XML nebo JSON, které zahrnují informace o novém zdroji. Informace v požadavku závisí na typu zdroje, který chceme vytvořit.

Příklad požadavku ve formátu JSON, kdy se snažíme vytvořit nového uživatele:

POST http://localserver/wp-json/wp/v2/users
HOST: localserver
Content-Type: application/json
{
  "user": {
    "name": "NewUser1",
    "siteRole":  "Publisher"
  }
}

Jak komunikovat s REST API v praxi?

Pokud jste si práci s API otestovali a chcete s ní pracovat při vývoji aplikace, využijete k tomu typicky některou z knihoven, skrze kterou lze v daném programovacím jazyku komunikovat přes protokol HTTP, například v PHP je to knihovna cURL.

Pro zaslání požadavku na REST API a zpracování jeho odpovědi můžeme vyjít z následujícího příkladu.

<?php
// Funkci curl_init() předáme adresu end pointu, na který si požadavek přejeme zaslat.
// Funkce nám vrátí identifikátor spojení, na který se dále budeme odvolávat pomocí zvolené proměnné $ch.

$ch = curl_init('http://www.example.com/wp-json/wp/v2/posts');

// Pomocí funkce curl_setopt() můžeme požadavek na end point přesněji specifikovat a nastavit chování cURL během zasílání požadavku a získávání odpovědi.
// V našem případě si budeme zejména přát odpověď vrátit jako výsledek funkce curl_exec().

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Též budeme chtít jen tělo odpovědi bez HTTP hlaviček.

curl_setopt($ch, CURLOPT_HEADER, 0);

// Pokud se vše podaří a server nám odpoví, odpověď nám vrátí funkce curl_exec().

$result = curl_exec($ch);

// Spojení uzavřeme.

curl_close($ch);

// V proměnné $result máme tedy odpověď serveru, která v případě WordPress REST API je ve formátu JSON.
// Data ve formátu JSON pro další zpracování musíme ještě převést na nativní PHP typ array či object. K tomu nám slouží funkce json_decode().

$data = json_decode($result);

Už si s REST API ve WordPressu rozumíte nebo vám něco není jasné? Napište nám a my vám rádi pomůžeme. V dalším díle seriálu si můžete znalosti ještě prohloubit – v několika krocích vám vysvětlíme, jak s pomocí REST API vytvořit aplikaci na publikování a kategorizování nevydaných příspěvků.

Začněte s WordPress REST API na serverech od MasterDC

WordPress instalaci můžete spustit na serverech v MasterDC s administrací. Managed servery jsou ve správě našich administrátorů, kteří se postarají o nerušený běh služby, zařídí instalaci i aktualizaci software a vyjdou vstříc vašim požadavkům. Nabízíme dvě formy administrace pro virtuální servery, cloud i dedikované servery.