web-dev-qa-db-de.com

Ist es besser eine zu platzieren? REST API auf einer Subdomain oder in einem Unterordner?

Wir haben eine Webanwendung, die mit der URL http://example.com gehostet wird. Jetzt möchten wir einen Teil dieser Anwendung als erholsamen Service erweitern und diskutieren über das beste URL-Muster. Ich habe gesucht, aber keine konkrete Anleitung gefunden.

Sollen wir das URL-Muster http://api.example.com oder http://exaple.com/api/v1 haben?

Gibt es eine Standardanleitung dafür?

27

Es hängt von Ihren Bedürfnissen ab.

Wenn Sie http://api.example.com verwenden, wird Ihre API zu einer Unterdomäne. Grundsätzlich ist dieses URL-Muster gut, wenn Ihr REST -Dienst von mehreren Clients verwendet werden soll. Wenn jedoch nur ein Client mit Ihrer API verbunden ist, ist das Muster http://example.com/api/ v1 ist gut. Wenn Sie jedoch mehr APIs mit mehr verbundenen Clients hinzufügen möchten, sollten Sie http://example.com/api/v1 verwenden. Betrachten Sie beispielsweise Folgendes.

http://example.com/reportapi/apioperation?parameters

http://example.com/paymentapi/apioperation?parameters

http://example.com/searchapi/apioperation?parameters

Last but not least verwendet Paypal das Muster http://example.com/api/v1 .

10
Jobert Enamno

Ich denke, Sie sollten weder http://api.example.com noch http://example.com/api/v1 verwenden.

Stattdessen würde ich vorschlagen, http://example.com/api und Inhaltsaushandlung für die Versionierung zu verwenden.

Hier sind meine Gedanken, warum:

Verwenden einer Unterdomäne:

Gemäß der URI-Schemaspezifikation definieren Sie die API im Berechtigungsteil der URI, der zum Definieren Ihres Hosts verwendet wird, anstatt eine Anwendung oder API auf Ihrem Host zu definieren. Sie erstellen tatsächlich eine andere Adresse für Ihre API. Dies bedeutet, dass die Authentifizierung für api.example.com möglicherweise nicht wie für example.com funktioniert.

Ein triftiger Grund hierfür könnte sein, wenn eine neue Instanz für mobile Geräte entworfen wird, z. mobile.example.com, aber ich würde dies eher als eine infrastrukturelle und nicht als eine funktionale Entscheidung betrachten.

Verwenden eines nicht versionierten Pfads in der Hauptdomäne:

Hier gibt es zwei Informationsbits: Eine zeigt an, dass eine API-Ressource vorhanden ist, und die zweite gibt die Versionsnummer dieser API-Ressource (v1) an.

Es ist nicht schlecht, mit /api/ zwischen der API und beispielsweise Ihrer Webansicht zu unterscheiden, die unter /web/ ausgeführt werden kann. Dies kann als gängige Best Practice angesehen werden.

Ich bin nicht sicher, ob Sie dies beabsichtigt haben, aber Ihre Frage enthält eine Frage zur Lösung der API-Versionierung. Persönlich denke ich, dass die API-Versionierung nicht über URLs erfolgen sollte, da diese so lange wie möglich stabil bleiben sollen. Coole URIs ändern sich nicht! Verwenden Sie stattdessen Informationen zum HTTP-Inhaltstyp, um Ihre API zu versionieren. Ich fand diese Methode tatsächlich in VMware-Dokumentation . Außerdem ist hier ein ziemlich alter, aber immer noch nützlicher Beitrag über die Versionierung von Inhaltstypen von Peter Williams .

1
brazo

Dies ist ein Fall von Kompromissen, bei dem es keine einzige beste Lösung gibt.

Wenn beispielsweise Ihr http://example.com/ Inhalt über eine Standard-Weboberfläche sowie über die API bereitstellt, benötigen Sie so etwas wie http://api.example.com/api/<version>/<the usual resource pattern>, um den browserbasierten Anwendungszugriff von der API-Interaktion zu trennen. Macht das Sinn?

Beispiel: api.rottentomatoes.com

Selbst wenn Ihre Domain für API-Aufrufe reserviert ist, ist es sinnvoll, das obige Muster trotzdem zu verwenden und http://example.com/ für andere Interaktionsmöglichkeiten mit Ihrer Anwendung zu reservieren. Zum Beispiel möchten Sie vielleicht http://example.com/mobile/ , etc.

0
TheWhiteRabbit