Nur noch kurz die Welt retten … ein API bauen

Teil 2: Eine Einführung in Apigility
Kommentare

Im zweiten Teil der Einführung in Apigility beschäftigen wir uns mit damit, dem Rest Service, den wir erstellt haben, mit einem Schreibzugriff auszustatten. Außerdem werfen wir einen Blick auf die Authentifizierung und bringen alles miteinander in Einklang.

Im ersten Teil der Einführung in Apigility haben wir die Grundlagen besprochen und das Projekt verlinkt, damit Sie das im Artikel besprochene Projekt nachvollziehen können.

REST Service mit Schreibzugriff

Bisher haben unsere REST Services nur einen lesenden Zugriff auf die Daten in der Datenbank ermöglicht. Als Nächstes möchten wir einen REST Service für Wetten auf das richtige Ergebnis eines Spieles umsetzen. Dafür steht die Tabelle „bets“ in der Datenbank bereit, die noch keinerlei Daten enthält. Dafür navigieren wir mithilfe des Menüs zu den APIs, wählen „WM2014API“ aus und legen einen neuen DB Connected REST Service an. Unser API soll nur das Anlegen und Löschen von Tipps sowie das Lesen unterstützen, sodass wir nur die GET-, POST- und DELETE-Methoden unterstützen möchten. Als Nächstes müssen die vier Felder für die Wetten definiert werden. Rufen Sie dafür den „fields“-Reiter auf und wechseln Sie in den Editiermodus. Legen Sie dafür zuerst die vier Felder „id“, „match“, „goals1“ und „goals2“ an. Da wir auch neue Tipps ermöglichen möchten, müssen wir für die einzelnen Felder auch eine Validierung konfigurieren. Für die „id“ geben Sie eine Beschreibung ein und ändern den Required-Parameter auf „no“, das dies der Primärschlüssel ist, der von MySQL automatisch inkrementiert wird – eine Validierungsmeldung benötigen wir somit nicht. Bei den anderen drei Feldern geben Sie neben der Beschreibung jeweils eine Validierungsmeldung an und fügen jeweils einen Validator ZendI18nValidatorInt hinzu. Speichern Sie nun die Konfiguration der Felder ab. Weitere Informationen zur Validierung von Inhalten finden Sie ebenfalls in der Dokumentation. Bei der Dokumentation der Wetten müssen Sie nun nicht nur die HTTP-Methode GET, sondern auch die anderen HTTP-Methoden dokumentieren. Wechseln Sie in den Editiermodus und erstellen Sie alle Beschreibungen und für alle HTTP-Methoden auch die Response bzw. Request Bodies. Diese können Sie sich ebenfalls wieder mithilfe des Buttons „generate form configuration“ automatisch erstellen lassen. Speichern Sie nun die Dokumentation ab. Jetzt können Sie den REST Service mit Postman testen. Da bisher noch keine Wetten in der Datenbank vorhanden sind, müssen wir zuerst eine neue Wette anlegen. Geben Sie dafür im Postman den Request-URL http://phpmagazin.apigility/bets ein und ändern Sie den HTTP-Methode auf POST. Klicken Sie auf den „form-data“-Button und fügen Sie das neue Feld „match“ als Key und den Wert „1“ für das Eröffnungsspiel hinzu. Zusätzlich fügen Sie die beiden Felder „goals1“ und „goals2“ hinzu und geben einen Tipp ab. Wenn Sie den Request absenden, sollten Sie als Ergebnis die neu erstellte Entität zurückerhalten. Geben Sie ein paar weitere Tipps ab. Wenn Sie danach die HTTP-Methode auf GET ändern, sollten Sie eine Liste Ihrer bisherigen Wetten erhalten. Um einen Tipp zu löschen, ändern Sie den Request-URL z. B. auf http://phpmagazin.apigility/bets/1 und die HTTP-Methode auf DELETE. Wenn Sie den Request absenden und sich danach nochmal die Liste aller Wetten anzeigen lassen, sollte der Eintrag wieder entfernt worden sein. Damit haben wir sichergestellt, dass unser REST Service für die Wetten funktioniert. Zum Abgleich können Sie sich einfach den Branch „step4“ auschecken.

Authentifizierung

Bisher konnte jedermann unser API lesend und schreibend verwenden. Jetzt möchten wir zumindest den Schreibzugriff des REST Service für die Wetten einschränken. Apigility unterstützt die Authentifizierung per HTTP Basic, HTTP Digest und OAuth2. Wir möchten an dieser Stelle die Authentifizierung per HTTP Basic einrichten. Dafür rufen Sie für unser API „WM2014API“ im Untermenü den Punkt „Authorization“ auf. Sie sollten dort einen Hinweis „No Authentication configured!“ angezeigt bekommen, der uns darauf hinweist, dass wir noch gar keine Authentifizierung konfiguriert haben. Das ignorieren wir erst einmal, aktivieren die Authentifizierung für die HTTP-Methoden POST, PATCH, PUT und DELETE und speichern. Unsere REST Services unterstützen derzeit zwar nur POST und DELETE, aber wir wollen jetzt schon einmal für die Zukunft vorbauen. Somit haben wir für unser API für alle schreibenden HTTP-Methoden die Authentifizierung eingerichtet. Jetzt klicken Sie im Hauptmenü auf „Settings“ und dann auf „Authentication“, um die Konfiguration der Authentifizierung zu starten. Wählen Sie „HTTP Basic“ aus. Bei „Authentication Realm“ geben Sie „api“ ein und für den Ort des htpasswd-Files „data/htpasswd“. Wenn Sie versuchen zu speichern, erhalten Sie einen Hinweis, dass die Password-Datei nicht gefunden werden konnte. Diese müssen wir noch anlegen. Der einfachste Weg erfolgt über das Apache2-Tool htpasswd. Um einen Nutzer „wm2014“ mit dem Passwort „wm2014“ anzulegen, rufen Sie dafür Folgendes auf und geben danach das Passwort doppelt ein. Danach sollten Sie die Datei im Verzeichnis /data/ vorfinden: htpasswd data/htpasswd wm2014. Alternativ können Sie sich eine solche Datei auch online generieren lassen und dann manuell unter /data/htpasswd speichern. Wenn Sie jetzt erneut versuchen, die HTTP-Basic-Einstellungen mit Apigility zu speichern, sollten Sie damit Erfolg haben. Rufen Sie danach noch einmal für das API „WM2014API“ im Untermenü den Punkt „Authorization“ auf und der Warnhinweis sollte verschwunden sein. Nun ist es an der Zeit, im Postman erneut einen POST Request abzusenden, um einen neuen Tipp abgeben zu können. Da Postman eine Historie bereitstellt, können Sie einen Ihrer letzten POST-Befehle nochmals aufrufen und absenden. Als Antwort sollten Sie einen Hinweis erhalten, dass der Zugriff nicht erlaubt ist, sowie den HTTP-Status 403. Postman bietet einen eigenen Reiter „Basic Auth“ an, um einen Authorization Header generieren zu können. Geben Sie dort den Benutzernamen „wm2014“ und das Passwort „wm2014“ ein und klicken Sie auf „Refresh Headers“. Jetzt sollte Ihrem Request ein neuer Header hinzugefügt worden sein. Wenn Sie den POST Request erneut absenden, sollten Sie keine Fehlermeldung mehr erhalten. Senden Sie für denselben Request-URL einen GET Request ab, und Sie sollten Ihren neuen Tipp in der Liste finden können. Probieren Sie auch aus, eine Wette löschen zu wollen. Ohne Authorization Header sollte das nicht funktionieren, nur mit der Angabe des entsprechenden Headers sollte das Löschen klappen. Zum Abgleich können Sie sich einfach den Branch „step5“ auschecken.

REST Service mit Authentifizierung nutzen

Abschließend möchten wir unsere kleine Beispielanwendung noch so erweitern, dass wir damit Tipps abgeben können. Wenn Sie den Branch „step5“ ausgecheckt haben, finden Sie die notwendigen Änderungen bereits im Modul WM2014Bet. Um einen POST Request versenden zu können, wurde zuerst der WM2014BetServiceAbstractService um eine sendPostRequest()-Methode erweitert (Listing 7). Auch hier kommt die Komponente ZendHttpClient zum Einsatz. Wichtig ist, dass die Authentifizierungsparameter festgelegt sowie die POS-Parameter und der Encoding Type übergeben werden. Neu ist der WM2014BetServiceBetService, der ähnlich wie die beiden anderen Services aufgebaut ist und eine save()-Methode enthält, die für das Speichern einer neuen Wette verwendet werden kann. Diese Methode, die in Listing 8 abgebildet ist, bekommt die ID des Spiels sowie die Daten für die getippten Tore übergeben.

setMethod('POST');
    $client->setParameterPost($postData);
    $client->setEncType(Client::ENC_FORMDATA);
    $client->setAuth('wm2014', 'wm2014', Client::AUTH_BASIC);
    $client->setHeaders(
      array(
        'Accept' => 'application/json',
      )
    );

    $response = $client->send();
    $response = $response->getContent();
    $data     = Json::decode($response);
    return $data;
  }
}
 $matchId,
      'goals1' => $data['goals1'],
      'goals2' => $data['goals2'],
    );

    $betData = $this->sendPostRequest($this->getRestRoute(), $postData);
    return $betData;
  }
}

Zum Abgeben eines Tipps wird ein Formular BetForm benötigt, das in Listing 9 (zu finden auf GitHub) gezeigt wird. Das Formular enthält lediglich zwei Eingabefelder für die Tore sowie einen Submit-Button zum Absenden des Tipps. Die Ausgabe des Formulars wurde in show.phtml des View-Skripts integriert, das Sie in Listing 10 (zu finden auf GitHub) finden. Dabei wurde die Tabelle um eine neue Zeile erweitert, und darin werden die einzelnen Formularelemente entsprechend ausgegeben. Um das Formular an den View zu übergeben, wurde der WM2014BetControllerIndexController erweitert (Listing 11). Nun können zum einen der BetService und zum anderen die BetForm von außen injiziert werden. Zudem wurde die showAction()-Methode so erweitert, dass beim Absenden eines POST Requests die Formulardaten an die save()-Methode des BetService übergeben werden und nach dem Speichern eine Umleitung auf dieselbe Seite erfolgt.

betService = $betService;
  }

  public function getBetService()
  {
    return $this->betService;
  }

  public function setBetForm($betForm)
  {
    $this->betForm = $betForm;
  }

  public function getBetForm()
  {
      return $this->betForm;
  }

  [...]
  public function showAction()
  {
    $id = $this->params()->fromRoute('id');
    if ($this->getRequest()->isPost()) {
      $this->getBetService()->save($id, $this->params()->fromPost());
      return $this->redirect()->toRoute('wm2014-bet/action', array(), true);
    }
    $viewModel = new ViewModel();
    $viewModel->setVariable('match', $this->getMatchService()->fetchOne($id));
    $viewModel->setVariable('teams', $this->getTeamService()->fetchOptions());
    $viewModel->setVariable('form', $this->getBetForm());
    return $viewModel;
  }
}

Wenn Sie jetzt mit dem Link http://phpmagazin.apigility/wm2014-bet/show/1 das Eröffnungsspiel im Browser aufrufen, sollte das Ergebnis wie in Abbildung 7 aussehen. Geben Sie nun einen Tipp ab und versenden Sie die Daten. Ob Ihr Tipp angekommen ist, können Sie wieder mit Postman überprüfen. Natürlich ist diese Beispielanwendung noch etwas unvollständig. Fehler werden nicht abgefangen, die bisherigen Tipps könnten bei jedem Spiel ausgegeben werden und eine Liste aller Tipps mit Statistik und Verteilung wäre sicherlich auch denkbar. Die Implementierung dieser Anforderungen bleibt aber Ihrer eigenen Kreativität überlassen.

Abb. 7: Versuchen Sie ihr Glück!

Abb. 7: Versuchen Sie ihr Glück!

 

Fazit

Mit Apigility ist es auf einfache Weise möglich, standardisierte APIs mithilfe von REST oder RPC zu erstellen, zu dokumentieren und zu betreiben. Inhalte können gefiltert und validiert werden und Sie können die Authentifizierung für Ihr API einrichten. Diese Einführung konnte nur einen grundlegenden Einblick in den Einsatz und die Möglichkeiten von Apigility bieten. Die Dokumentation bietet zusätzlich noch Informationen zum Deployment, zur Versionierung und für weitere Fragestellungen, wie die Integration in ein bestehendes Projekt oder das Hochladen von Dateien über das API. Das Projekt soll in den kommenden Monaten weiter vorangetrieben werden und auch in Kürze zusätzliche Features bereitstellen.

Alle Teile: Teil 1, Teil 2

Unsere Redaktion empfiehlt:

Relevante Beiträge

Meinungen zu diesem Beitrag

X
- Gib Deinen Standort ein -
- or -