Sollte ein REST-API-Parameter jemals beeinflussen, welche anderen Parameter benötigt werden?

Zum Beispiel kann ich ein Fahrzeug erstellen, und muss es einen Typ geben, der "Automobil" oder "Flugzeug" sein kann. Automobile benötigen einen Reifengrößenparameter und Flugzeuge benötigen einen Spannweitenparameter. Ähnliche Frage, ob ein REST-API-Parameter jemals beeinflussen sollte, welche Eigenschaften in der Antwort benötigt werden.Sollte ein REST-API-Parameter jemals beeinflussen, welche anderen Parameter benötigt werden?

/vehicles: 
    post: 
     summary: Creates a vehicle 
     description: Adds a new vehicle of given type. 
     parameters: 
     - name: vehicle (what is the purpose of this????) 
      in: body 
      description: The vehicle to create. 
      schema: 
      required: 
       - type 
       - speed 
       - color 
      properties: 
       type: 
       type: string 
       speed: 
       type: interger 
       color: 
       type: string 
       wingspan: 
       type: string 
       tiresize: 
       type: string 
     responses: 
     204: 
      description: Vehicle succesfully created. 
     400: 
      description: Vehicle couldn't have been created.

Quelle

2016-09-20 user1032531

Während dies in der Praxis passiert, ist es am besten zu vermeiden, da es die Dokumentation Ihrer API erschwert. Dies gilt insbesondere, wenn Sie eine Dokumentationstechnologie wie Swagger verwenden, die diese "bedingt erforderlichen" Parameter nicht zulässt. Indem Sie sie hinzufügen, fügen Sie Ihrer API tatsächlich zusätzliche Semantiken hinzu, die nicht in den Swagger-Dokumenten dokumentiert sind.

Ein besserer Ansatz ist, anstatt einen "Typ" -Parameter verschiedener Fahrzeugtypen zu verwenden, verwenden Sie einfach eine separate URL für jeden Typ. Auf diese Weise können Sie die erforderlichen/optionalen Parameter für jeden Fahrzeugtyp ordnungsgemäß dokumentieren.

/vehicles/automobile: 
    post: 
    parameters: 
     schema: 
     required: 
      - tyresize 
     properties: 
      tyresize: 
      type: string 
/vehicles/airplane: 
    post: 
    parameters: 
     schema: 
     required: 
      - wingspan 
     properties: 
      wingspan: 
      type: string

Quelle

2016-09-20 15:15:19 tonicsoft

Dank tonicsoft. Ich kann bestätigen, dass es in der Praxis passiert, als ich es tat! Nachdem ich in Swagger eingedrungen bin, habe ich das Gefühl, dass ich es vielleicht nicht sollte, und schätze deine Bestätigung. Randnotiz ... Braucht Ihre Konfiguration einen 'Namen: Automobil' und' in: Körper'? Ich lese https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-2-the-basics/, und es fügt immer einen Namen hinzu, aber ich kenne den Zweck nicht. Danke – user1032531

Froh, dass Sie es hilfreich fanden. Ja ich glaube die Konfiguration benötigt immer einen Namen (Entschuldigung für mein schlampiges Beispiel). Alle Parameter benötigen einen Namen, genau wie Methoden in objektorientiertem Code. Der Name ist so, dass Sie den Wert des Parameters tatsächlich angeben können, wenn Sie die API verwenden: 'curl -X POST --header 'Inhaltstyp: application/json' -d '{" vehicle ": ....} '' – tonicsoft

Danke nochmal tonicsoft. Dein Kommentar zeigt 'curl -X POST --header 'Content-Type: application/json' -d '{" vehicle ": ....}' '. Ich nehme es, wenn erweitert meinst du 'curl -X POST --header 'Content-Type: application/json' -d '{" vehikel ": {{" speed ": 123," color ":" blau "," spannweite ": 321}}" "http: // example.com/vehicles/aeroplane". Warum nicht 'curl -X POST --header 'Inhaltstyp: application/json' -d '{" Geschwindigkeit ": 123," color ":" blau "," Spannweite ": 321}' 'http:// example.com/vehicles/aeroplane' Arbeit, und das übergebene Objekt wird die (super sorry, all its know) super globale Variable PHP $ _POST? – user1032531

Sollte ein REST-API-Parameter jemals beeinflussen, welche anderen Parameter benötigt werden?

Antwort

Verwandte Themen