I have the following endpoints configured for managing types of food

• POST ~ /food/types
• GET ~ /food/types
• GET ~ /food/types/{id}
• PUT ~ /food/types/{id}
• Delete ~ /food/types/{id}

I'm trying to represent a clone operation in my REST API and wanted to avoid the use of Verbs in my endpoints.

After some research I've come up with the following as it conforms the most out of other solutions i could think of to basic REST principles:

POST ~ /food/types?sourceId={id}

This would mean that the method for this endpoint (in a typical MVC framework) would need to conditionally handle both the creation when a JSON payload is sent, and the duplication of a resource when a query parameter is provided.

I'm trying to think how i can express that in my OpenAPI specification document (v3.0.2)

Here is what i've got so far:

/api/food/types:
    post:
      summary: Create a new type of food
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: ./response/food-type.yaml
        '400':
          description: Bad Request
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./request/food-type.yaml
      description: Create a new type of food
      tags:
        - Food Type
    parameters: []

The request/food-type.yaml contains an object with two required parameters:

1. Name,
2. Category

When my framework validates the request against the OpenAPI specification, i want it to sometimes ignore the request body if and only if, a request parameter has been provided with a 'sourceId' parameter.

Is this type of thing even possible to express in OpenAPI 3 , or am i going about this the wrong way?

Simply put, is it possible to ignore the request body when a specific query parameter has been provided in a post request using OpenAPI 3.

And following that question, is my approach to REST lacking, and is there a better way i could represent the cloning of a resource in my API?

CodePudding user response：

Use the body of the message instead to describe the source:

POST /food/types {"clone": "{id}"}

You can even use verb if you convert them into nouns:

POST /food/type-cloning {"source": "{id}"}