cancel
Showing results for 
Search instead for 
Did you mean: 

Solution to not use property in /post, but use in /get, /put, /delete

Occasional Visitor

Solution to not use property in /post, but use in /get, /put, /delete

We're building an API that will allow vendors to submit test scores. They'll be able to GET, POST, PUT, and DELETE. They can insert, update, and delete tests. To insert test scores, they'll need to provide us a unique test ID of their own (we'll call it vendor_test_id) as well as a user ID (user_id) and a test score (score). Since there are multiple vendors with the potential for overlapping vendor_test_ids, we store our own ID (test_id). Ideally, in order to update or delete, they'll need to use test_id instead of vendor_test_id. I would like to write this documentation so that when they use the example functionality, test_id doesn't show up in /post since it's not applicable there.

 

I could write two different definitions – one for /post and one for the /get and /put. But the amount of properties inside of our actual "test" API is 30+ and it has already changed a few times. I'd rather not need to remember to change it in two places.

 

Below is an example of what I'm trying to do, but I know it's not valid.

 

paths:
  /tests:
    get:
      tags:
        - "test"
      description: ""
      operationId: "getTests"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              test_id: "integer" #I know this isn't valid
              $ref: "#/definitions/Test"
    post:
      tags:
        - "test"
      description: ""
      operationId: "addTest"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Test"
definitions:
  Test:
    type: "object"
    properties:
      vendor_test_id:
        type: "integer"
        example: "5"
      user_id:
        type: "integer"
        example: "6"
      score:
        type: "integer"
        example: "100"