Table of Contents

Adding POST and PUT requests to OAS

Now you’ll add to the YAML file: a POST, PUT, and some responses.

Add a new schema

  1. You are going to add information about the request body for a POST request to create a new playlist, with a name and a list of IDs for each of the songs in the playlist. Here’s an example of JSON in the request body:
    {
      "name": "Mellow jazz",
      "songIds": [183, 13, 435, 98, 689]
    }
  2. Add a definitions key at the bottom of the file. Under that, add a newPlayList key (indented) and then add a string property for the name and an array of integers, which are the song IDs in the playlist.
    definitions:
      # New play list
      newPlaylist:
        properties:
          name:
            type: string
          songIds:
            type: array
            items: 
              type: integer
        required:
          - name
  3. At this stage, you should see no errors, but you should see a little warning saying that the definition is not used. Remember, if you are seeing errors, click Save and try a refresh on the page.


Add a POST request

  1. Add a POST Request to create a new playlist. Here’s a sample request \\
    POST https://virtserver.swaggerhub.com/Orange-formation/musicAPI/1.0.0/playlist
     
    {
      "name": "Mellow jazz",
      "songIds": [183, 13, 435, 98, 689]
    }
  2. Since the /playlist key has been already defined for the get request, you don’t need a new path. You can add the POST request to the existing /playlist path.
  3. Below the get section, add a similar section called post. (Same indentation.)
        # Create a new playlist
        post:
          # Body 
          parameters:
            - name: newPlaylist
              in: body
              required: true
              schema: 
                $ref: '#/definitions/newPlaylist'
     
          # Incomplete response (to finish later)
          responses:
            # Response code
            200:
              description: Successful response
  4. The code above does the following:
    1. Add a parameters key, just like in the get section.
    2. For name, use newPlaylist
    3. For in, use body
    4. For required, use true
    5. For schema, refer to the newPlaylist object you’ve created in the definitions section above.
  5. Notice that the warning has gone away, and also that your new POST request appears in the documentation on the left. There is a Schema section that will show your schema once you expand it all: the name as a string, and songIds as an array of integers.


  6. Click on Try it out. Fill in the newPlaylist body as shown below and click Execute.


  7. If the request is executed successfully, you should see the response status code 200.