user1032531 user1032531 - 2 months ago 14
reST (reStructuredText) Question

Should a REST API parameter ever influence which other parameters are required?

For instance, I can create a vehicle, and must give it a type which can be "automobile" or "airplane". Automobiles require a tire size parameter and airplanes require a wingspan parameter. Similar question regarding whether a REST API parameter should ever influence which properties are required in the response.

/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.

Answer

While this happens in practice, it is best avoided as it makes it difficult to document your API. This is particularly true if you are using a documentation technology such as Swagger which does not allow these "conditionally required" parameters. By adding them, you are actually adding extra semantics to your API which are not documented in the Swagger docs.

A better approach is, instead of having a "type" parameter of different vehicle types, just use a separate URL for each type. This will allow you to properly document the required/optional parameters for each vehicle type.

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