So halten Sie die Repräsentation von FKs in Eingabe/Ausgabe einheitlich (RESTful JSON API)

Question

Wir schreiben unsere erste Nicht-XML-API und ich möchte nach den Best Practices für die Darstellung verwandter Ressourcen in der API fragen. Lassen Sie mich es auf einer user Ressource und der damit verbundenen Ressource - organization erklären.

In XML das ist ziemlich einfach:

1. Antwortkörper (GET) - es enthält auch Ressourcen-IDs als URIs:

   GET /users/321/ 
   
   <?xml version="1.0" encoding="UTF-8" ?> 
   <user> 
       <!-- ... ---> 
       <organization name="Lorem Ipsum Ltd." href="/organizations/123/">123</organization> 
   </user> 
   

2. anfordern Körper (POST/PUT/PATCH) - verwendet IDs:

   PATCH /users/321 
   
   ...&organization=123 
   

3. URI Filter - verwendet IDs von verwandten Ressourcen:

   GET /users/?organization=123 
   
   <?xml version="1.0" encoding="UTF-8" ?> 
   <users> 
       <!-- ... ---> 
   </users> 
   

Jetzt, da JSON keine Attribute verwenden, es ist keine 1: 1-Übergang.

1. Antwortkörper (GET):

   Statt IDs als Werte verwenden, wechselten wir zu URIs, um die Verbundenheit Prinzip der REST einzuhalten:

   GET /users/321/ 
   
   { 
       ..., 
       "organization": "/organizations/123" 
   } 
   

2. Anfragetext (POST/PUT/PATCH) - akzeptiert URIs (Beispiel aus Gründen der Lesbarkeit nicht codiert):

   PATCH /users/321 
   
   ...&organization=/organizations/123/ 
   

3. URI-Filter - um die URIs sauber zu halten, wir IDs noch statt URIs verwenden, wenn sie über GET-Parameter Filterung:

   GET /users/?organization=123 
   
   { 
       "users": [ 
        ... 
       ] 
   } 
   

Das letzte Bit die Gleichförmigkeit des Wertes bricht (ID vs. URI) zwischen Anfrage und Antwort, aber wir bevorzugen die Verwendung von IDs anstelle von URIs, weil IDs lesbarer sind und weil es Fälle geben kann, in denen wir mehr als einen Wert in einen Filter setzen müssen (z. B. ?organization__in=123,124).

Also meine Frage ist, Wie halten Sie Anfrage/Antwort Darstellung der zugehörigen Ressourcen einheitlich über Ihre API? Best Practices, Standards oder nur gesunder Menschenverstand? Oder ist das Obige vielleicht eine unnötige Sorge?

bearbeiten: Um zu klären, ich frage, wie würden Sie die API in Bezug auf die URI-Struktur (GET-Parameter) Design und das Format der Request/Response-Daten. Ich bin nicht fragen über die technische Umsetzung.

Ein Ansatz ist es, zu einer ausführlicheren Darstellung zu wechseln, die Benutzern der API ein bisschen mehr Daten gibt, aber es löst immer noch nicht das Uniformitätsproblem. Beispiel:

GET /users/321/ 

{ 
    ..., 
    "organization": { 
     "ud": 123, 
     "name": "Lorem Ipsum Ltd.", 
     "uri": "/organizations/123" 
    } 
} 

Hinweis - ähnliche Frage (nicht kopieren): REST API - include related object details or just ID's

Answer 1

Interessante Frage, und ich sehe den Vorteil, eine Möglichkeit, dies zu tun. Eine Schnittstelle oder Vererbung wird nicht funktionieren, da alles, was Sie wirklich zurückgeben, eine Zeichenfolge ist (figurativ). Wie wäre es mit einer Gruppe von Helfern, die auf einen Typ reagieren und die Antworten für Sie erstellen? Sie könnten es T übergeben und es würde durch das Objekt iterieren, das die Antwort gemäß den Regeln und Mustern erstellt, die Sie entwerfen. Sie könnten einen GetBuilder (x) haben und er würde von Ihrem Get aufgerufen werden. Dies bietet einen einzigen Ort für die Verarbeitung der Rückgaben und bietet Einheitlichkeit.