Die WordPress-HTTP-API besteht aus einer Reihe von Funktionen, die dir helfen werden, HTTP-Aufrufe viel einfacher zu machen. Du brauchst nicht mehr mit file_get_contents oder cURL herumzuspielen, nur noch ein einziges einheitliches Interface. Das ist großartig, um mit APIs von Drittanbietern zu interagieren, besonders mit REST-vollen wie Twitter, Facebook, MailChimp und anderen.

Die Grundlagen von HTTP

Wir haben alle schon einmal HTTP in Aktion gesehen. In der Tat, wenn du zum ersten Mal im Web bist und dies das erste ist, was du liest, hast du bereits gesehen, wie HTTP seine Magie entfaltet. HTTP ist ein Netzwerkprotokoll, das verwendet wird, um alle Dateien und Daten (Ressourcen) über die Internetseiten (Interwebs) zu liefern.

Die Gleichung besteht im Wesentlichen aus zwei Teilen: der HTTP-Anfrage und der HTTP-Antwort, oder Transaktion. Sowohl die Anfrage als auch die Antwort sind in ihrer Struktur sehr ähnlich, beide haben vier Teile:

  • Eine Anfangszeile
  • Null oder mehr Kopfzeilen
  • Eine leere Zeile
  • Ein optionaler Körperinhalt

Die Anfangszeile

Anfragen benutzen die Anfangszeile, um drei Informationen zu senden: den Methodennamen, den Pfad und die HTTP-Version. Wenn du dir zum Beispiel die Hauptseite des Kinsta-Blogs ansiehst, siehst du dies in der Anfangszeile der Anfrage.

GET /blog/ HTTP/1.1

Die Responses liefern ebenfalls drei Informationen, wenn auch etwas unterschiedliche: Die HTTP-Version, den Response-Code und eine Beschreibung der Antwort. Wenn ihr eine Anfrage an den Kinsta-Hauptblog stellt, sendet es eine HTTP-Antwort mit der folgenden Anfangszeile:

HTTP/1.0 200 OK

Überschriften

Kopfzeilen enthalten verschiedene Informationen über die Anfrage oder die Antwort. HTTP 1.1 definiert 46 Arten von Headern, aber nur einer wird benötigt (nur für Anfragen), der „Host“-Header. Schaut euch den Screenshot aus meinen Chrome-Entwickler-Tools an, der einige der Header zeigt, die zusammen mit einer Anfrage an den Kinsta-Hauptblog gesendet werden:

HTTP request headers sent

Body

Der Body enthält normalerweise Daten über die angeforderte Ressource. Wenn du eine GET-Anfrage an den Haupt-Blog von Kinsta schickst, solltest du den HTML-Code erhalten, der benötigt wird, um die Seite (die Ressource) im Body-Inhalt darzustellen.

Mehr Informationen

Das ist alles, was du im Moment über HTTP wissen musst. Wir werden uns hauptsächlich auf den Methodennamen (GET,POST, etc), die Header und den Body konzentrieren. Wenn du mehr lernen möchtest, empfehle ich James Marshall’s Erklärung von HTTP, es ist eine sehr gut geschriebene Fibel für deine HTTP-Bedürfnisse.

Über Restful APIs

Restful APIs, oder die REST-Methodik, zielt darauf ab, eine einfache und standardisierte Möglichkeit zu bieten, mit einer Anwendung zu interagieren (hier kannst du mehr über die Grundlagen der WordPress REST API erfahren). Es wird oft in Verbindung mit HTTP verwendet, um ein sehr verständliches System von Interaktionen zu schaffen. Es basiert auf Pfaden und HTTP-Verben.

Die HTTP-Verben sind die gleichen wie die Methodennamen, die wir vorher gesehen haben, die gebräuchlichsten sind: GET, POST, PUT, DELETE. Ich denke, PUT ist das einzige mehrdeutige hier, betrachte es als einen Aktualisierungsbefehl. Wenn wir diese Verben zusammen mit Pfaden verwenden, können wir ein sinnvolles System aufbauen:

GET /post/1/ würde benutzt werden, um den Beitrag mit der ID 1 abzurufen. DELETE /post/1/ würde benutzt werden, um denselben Beitrag zu löschen. Wir könnten auch PUT /post/1/ benutzen, um es zu aktualisieren, indem wir relevante Informationen im Anfragetext und in den Kopfzeilen angeben.

Ich bin mir sicher, dass du sehen kannst, dass wir allein durch das Anhängen einer HTTP-Version an unsere obigen Codes tatsächlich die Anfangszeile einer HTTP-Transaktion haben, was nur ein Grund dafür ist, dass dieses System so mächtig ist.

Die WordPress HTTP-API benutzen

Bewaffnet mit all diesem Wissen können wir uns leicht vorstellen, wie die WordPress HTTP API funktioniert. Die vier Methoden, die benutzt werden, um Anfragen zu stellen und die Antworten abzufangen, sind

  • wp_remote_get()
  • wp_remote_post()
  • wp_remote_head()
  • wp_remote_request()

Die ersten beiden Funktionen sind selbsterklärend, sie verwenden die GET- bzw. POST-Methode in der Anfrage. Die dritte Funktion benutzt die HEAD-Methode, etwas, worüber wir noch nicht gesprochen haben. Diese Methode wird verwendet, um nur die Header einer Antwort abzurufen. Dies kann eine Menge Overhead sparen, wenn wir nur einige Metadaten über eine Ressource benötigen. Die letzte Funktion ist eine generische Funktion, du kannst innerhalb der Parameter der Funktion angeben, welche Methode du verwenden möchtest.

Es gibt fünf zusätzliche Funktionen, die wir verwenden können, um bestimmte Teile der Antwort abzurufen. Diese sind im Grunde genommen Shotcuts, um durch die Masse der Daten, die wir erhalten, zu navigieren:

  • wp_remote_retrieve_body()
  • wp_remote_retrieve_header()
  • wp_remote_retrieve_headers()
  • wp_remote_retrieve_response_code()
  • wp_remote_retrieve_response_message()

Unsere erste HTTP-Anfrage

Lass uns einen schnellen Test machen, indem wir die Header-Informationen aus dem Kinsta-Blog abrufen. Du kannst das überall innerhalb eines Plugins oder Themes machen, aber du solltest dich natürlich in einer Testumgebung befinden, um sicherzustellen, dass du keinen unerwünschten Text auf einer live Webseite ausgibst.

$response = wp_remote_head( 'https://kinsta.com/blog/' );
var_dump( $response )

Wie ihr an der Antwort, die wir unten erhalten, sehen könnt, ist der Body-Bereich leer (da wir die HEAD-Methode verwenden) und alle Header werden angezeigt. Um nur die Header ohne all die anderen Array-Mitglieder zu holen, könnten wir die wp_remote_retrieve_headers()-Funktion verwenden.

array (size=5)
  'headers' => 
    array (size=13)
      'server' => string 'nginx' (length=5)
      'date' => string 'Wed, 22 Jul 2015 14:22:07 GMT' (length=29)
      'content-type' => string 'text/html; charset=UTF-8' (length=24)
      'connection' => string 'close' (length=5)
      'vary' => string 'Accept-Encoding' (length=15)
      'x-pingback' => string 'https://kinsta.com/xmlrpc.php' (length=29)
      'x-powered-by' => string 'HHVM/3.8.0' (length=10)
      'link' => string '; rel="https://github.com/WP-API/WP-API"' (length=68)
      'x-frame-options' => string 'DENY' (length=4)
      'x-content-type-options' => string 'nosniff' (length=7)
      'strict-transport-security' => string 'max-age=31536000' (length=16)
      'x-kinsta-cache' => string 'HIT' (length=3)
      'content-encoding' => string 'gzip' (length=4)
  'body' => string '' (length=0)
  'response' => 
    array (size=2)
      'code' => int 200
      'message' => string 'OK' (length=2)
  'cookies' => 
    array (size=0)
      empty
  'filename' => null

Den Sinn der APIs verstehen

twitter wordpress api

Die größte Hürde, die ich für Entwickler sehe, ist die schiere Menge an neuem Zeug, das sie einbauen müssen, damit ein API-Aufruf funktioniert. Du musst über HTTP Bescheid wissen, wie man Anfragen stellt und auch, wie man sich richtig authentifiziert, ohne das wird jeder einzelne Aufruf fehlschlagen. Schauen wir uns ein Beispiel durch die Twitter API an, da sie eine großartige Dokumentation haben.

Wir werden uns die Application-only-Authentifizierung anschauen (was ein einfacherer Ablauf ist), ich werde die gleichen Schritte durchgehen, die Twitter vorschlägt. Bevor wir anfangen, solltest du eine Twitter-Applikation erstellen.

Du solltest in der Lage sein, den untenstehenden Code irgendwo in ein Theme oder ein Plugin einzufügen, aber stelle wie zuvor sicher, dass du eine Testseite benutzt!

Schritt 1: Verbraucherschlüssel und Geheimnis verschlüsseln

Sobald du eine Anwendung erstellt hast, solltest du einen Verbraucherschlüssel und ein Secret zur Hand haben. Um die Dinge einfacher zu machen, lass uns Konstanten erstellen, die diese Informationen für uns bereithalten.

define( 'TWITTER_CONSUMER_KEY', '12disnir382jeqwdasd23wdasi' );
define( 'TWITTER_CONSUMER_SECRET', '23wdajskduhtrq2c32cuq9r8uhuf' )

Die drei Schritte zur Erstellung einer kodierten Version davon sind in den Dokumenten dargelegt:

  • URL kodieren den Verbraucherschlüssel und das Verbrauchergeheimnis
  • Verknüpfe sie mit einem Doppelpunkt
  • Base64 kodiert den ganzen String

In PHP wird das ziemlich einfach zu bewerkstelligen sein, los geht’s!


$key = urlencode( TWITTER_CONSUMER_KEY );
$secret = urlencode( TWITTER_CONSUMER_SECRET );
$concatenated = $key . ':' . $secret;
$encoded = base64_encode( $concatenated );

Schritt 2: Einen Trägerspielstein bekommen

Anstatt dein eigentliches Passwort zu verwenden, sendest du Twitter deinen verschlüsselten String (der deine API-Anmeldedaten verwendet) und du erhältst einen temporären Pass, der für eine bestimmte Zeit gültig ist. Um dies zu tun, werden wir eine HTTP-Anfrage stellen, hier ist, was Twitter zu sagen hat:

  • Die Anfrage muss eine HTTP POST Anfrage sein.
  • Die Anfrage muss einen Authorization Header mit dem Wert Basic .
  • Die Anfrage muss einen Content-Type-Header mit dem Wert application/x-www-form-urlencoded;charset=UTF-8 enthalten.
  • Der Hauptteil der Anfrage muss grant_type=client_credentials sein.

Fangen wir mit den Grundlagen an. Wir wissen, dass wir eine POST-Anfrage benötigen, also werden wir wp_remote_post() verwenden. Die Funktion greift auf Parameter zurück; der erste ist die URL, der zweite enthält optionale Argumente. Die URL wird https://api.twitter.com/oauth2/token sein, den zweiten Parameter werden wir verwenden, um alle anderen Anforderungen zu erfüllen.

$args = array(
    'headers' => array(
        'Authorization' => 'Basic ' . $encoded,
        'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8'
    ),
    'body' => 'grant_type=client_credentials'
);
$response = wp_remote_post( 'https://api.twitter.com/oauth2/token', $args );

Header müssen als ein Array hinzugefügt werden, wobei der Header-Typ der Schlüssel ist, der Wert der Wert des Array-Mitglieds; Der Body sollte ein String sein. Bei Erfolg solltest du eine Antwort ähnlich der untenstehenden sehen.

array (size=5)
  'headers' => 
    array (size=23)
      'cache-control' => string 'no-cache, no-store, must-revalidate, pre-check=0, post-check=0' (length=62)
      'content-disposition' => string 'attachment; filename=json.json' (length=30)
      'content-encoding' => string 'deflate' (length=7)
      'content-length' => string '142' (length=3)
      'content-type' => string 'application/json;charset=utf-8' (length=30)
      'date' => string 'Wed, 22 Jul 2015 14:47:37 GMT' (length=29)
      'expires' => string 'Tue, 31 Mar 1981 05:00:00 GMT' (length=29)
      'last-modified' => string 'Wed, 22 Jul 2015 14:47:37 GMT' (length=29)
      'ml' => string 'A' (length=1)
      'pragma' => string 'no-cache' (length=8)
      'server' => string 'tsa_b' (length=5)
      'set-cookie' => string 'guest_id=v1%3A14375720938219946; Domain=.twitter.com; Path=/; Expires=Fri, 21-Jul-2017 14:47:37 UTC' (length=100)
      'status' => string '200 OK' (length=6)
      'strict-transport-security' => string 'max-age=631138519' (length=17)
      'x-connection-hash' => string 'd8b10926f99dwef93rd7edbe5a71a97a' (length=32)
      'x-content-type-options' => string 'nosniff' (length=7)
      'x-frame-options' => string 'SAMEORIGIN' (length=10)
      'x-response-time' => string '34' (length=2)
      'x-transaction' => string 'ef0ebwefweece62ef' (length=16)
      'x-tsa-request-body-time' => string '0' (length=1)
      'x-twitter-response-tags' => string 'BouncerCompliant' (length=16)
      'x-ua-compatible' => string 'IE=edge,chrome=1' (length=16)
      'x-xss-protection' => string '1; mode=block' (length=13)
  'body' => string '{"token_type":"bearer","access_token":"AAAAAAAAAAAAAAAAAAAAAFoafQAAAAAAqg%2BxmuH83hjsod6crH5bKTUX9Arc%3D5dWpp0XCTDjyiXxMC7LDLg8JbzPdGlCsJi2R1qjY1FMksTAFyG"}' (length=155)
  'response' => 
    array (size=2)
      'code' => int 200
      'message' => string 'OK' (length=2)
  'cookies' => 
    array (size=1)
      0 => 
        object(WP_Http_Cookie)[303]
          public 'name' => string 'guest_id' (length=8)
          public 'value' => string 'v1:143757645770219946' (length=21)
          public 'expires' => int 1500648457
          public 'path' => string '/' (length=1)
          public 'domain' => string '.twitter.com' (length=12)
  'filename' => null

Das Haupthighlight von all dem ist das Access-Token, das im Körper der Response zu finden ist. Das holen wir uns jetzt mit unseren praktischen WordPress-Funktionen. In Fortführung unseres vorherigen Beispiels könnten wir uns das Access-Token mit dem folgenden Code holen:

$body = wp_remote_retrieve_body( $response );
$body = json_decode( $body, true );
$access_token = $body['access_token'];

Schritt 3: Benutze den Trägerspielstein

Der letzte Schritt ist einfach, dieses Inhaber-Token in allen anderen API-Aufrufen zu verwenden. Wir müssen es als „Authorization“-Header mit dem Wert hinzufügen: Träger [Überbringer_Token]. Lass uns einen einfachen API-Aufruf machen, der die neuesten Tweets eines Benutzers über den user_timeline Pfad abruft.

$url = 'https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=danielpataki&count=3';
$args = array(
    'headers' => array(
        'Authorization' => 'Bearer ' . $access_token,
    ),
);

$response = wp_remote_get( $url, $args );
$tweets = json_decode( wp_remote_retrieve_body($response), true )

Am Ende von all dem wird die Variable $tweets eine Reihe von Tweets enthalten. Du kannst verschiedene Eigenschaften dieses Arrays verwenden, um den Tweet anzuzeigen oder die Daten zu manipulieren.

Schlussfolgerung

Wie du sehen kannst, ist es nicht so schwierig, die WordPress HTTP API zu benutzen, um sich mit externen Diensten zu verbinden. Viele der heutigen modernen APIs sind nach den gleichen REST-Prinzipien aufgebaut – wenn du einmal eines gelernt hast, wirst du schnell den Dreh bei den anderen herausbekommen.

Denke daran, dass du immer, wenn die Dokumentation dich auffordert, den Body zu benutzen, den Body benutzen solltest und wenn es nach Headern verlangt, einfach so viele wie nötig hinzufügen solltest. Dann schau dir die Antwort an, wandle sie in ein Array um, schnapp dir die Daten, die du brauchst, und benutze es, so einfach ist es.

Wenn jemand schon einmal mit einer besonders guten oder schlechten API gearbeitet hat, oder ihr ein paar Tipps und Tricks mit der WordPress HTTP API habt, lasst es uns in den Kommentaren wissen!

Daniel Pataki

Hi, my name is Daniel, I'm the CTO here at Kinsta. You may know me from Smashing Magazine, WPMU Dev, Tuts+ and other WordPress/Development magazines. Aside from WordPress and PHP I spend most of my time around Node, React, GraphQL and other technologies in the Javascript space.

When not working on making the best hosting solution in the Universe I collect board games, play table football in the office, travel or play guitar and sing in a pretty bad band.