HTTP Snippet Format

[sebastienlevert]

Based on this OpenAPI : https://github.com/sebastienlevert/jsonplaceholder-api/blob/main/openapi.yaml

(I made edits to the operation to illustrate some use cases.)

And this operation:

/posts:
    get:
      description: Get posts
      operationId: list-posts
      parameters:
      - name: userId
        in: query
        description: Filter results by user ID
        required: true
        style: form
        schema:
          type: integer
          maxItems: 1
      - name: title
        in: query
        description: Filter results by title
        required: false
        style: form
        schema:
          type: string
          maxItems: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/post'

    post:
      description: 'Create post'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/post'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/post'

components:
  schemas:
    post:
      type: object
      properties:
        userId:
          type: integer
        id:
          type: integer
        title:
          type: string
        body:
          type: string
  parameters:
    post-id:
      name: post-id
      in: path
      description: 'key: id of post'
      required: true
      style: simple
      schema:
        type: integer

The format should be the following:

• A comment with the HTTP Method and the URL Template. All path and query parameters should be there and marked as required or optional using the URL Template syntax. The description should come from the description of the method in the OpenAPI.
• Add a variable for every parameter (path or query) that are required. Leave the value of the variable to be empty and available for the dev to fill, unless there are examples that could show how to use it. The description should come from the description of the method in the OpenAPI.
• Have the base URL parameterized as {{url}}

# Base URL
@url = https://jsonplaceholder.typicode.com

### GET /posts?userId={userId}{&title}
# Filter results by user ID
@userId = 1

# Get posts
GET {{url}}/posts?userId={{userId}}

### POST /posts
# Create posts
POST {{url}}/posts
Content-Type: application/json

{
  "title": "",
  "body": "",
  "userId": 1
}

[maisarissi]

Should we consider some sort of auth as part of the snippet?

[sebastienlevert]

@maisarissi we could, based on the auth schemes and have the right Auth headers. What would be your suggestion on automating this?

[maisarissi]

I would suggest:

1 - use the settings.json file. So instead of the bellow code in the .http snippet file:

# Base URL
@url = https://jsonplaceholder.typicode.com

I would suggest the .http snippet file be:

### GET /posts?userId={userId}{&title}
# Filter results by user ID
@userId = 1

# Get posts
GET {{HostAddress}}/posts?userId={{userId}}

### POST /posts
# Create posts
POST {{HostAddress}}/posts
Content-Type: application/json

{
  "title": "",
  "body": "",
  "userId": 1
}

and add a rest-client.environmentVariables entry in the settings.json file with a remote or prod node:

{
    "rest-client.environmentVariables": {
        "$shared": { },
        "remote": {
            "hostAddress": "https://jsonplaceholder.typicode.com",
            "basicAuth": "Basic dXNlcm5hbWU6c2VjcmV0",
            "bearer": " Bearer AAAACSSXSXSV....SDSDSD"
        }
    }
}

This would allow folks to easily add as many environments as needed (like dev) later and then change easily the env that is been called, like the screenshot below:

If we go that way, we need to remove the @url from the .http file, because variable definitions in .http files override environment definitions.

2 - For the auth, based in auth scheme described in the OpenAPI description, I believe we should create/add the environment variables in the settings.json. So for example, if the /posts requires Basic auth, the .http file should be:

POST {{HostAddress}}/posts
Content-Type: application/json
Authorization: {{basicAuth}}

{
  "title": "",
  "body": "",
  "userId": 1
}

3 - I would say we should support "basicAuth", "bearer" and "apiKey". For Oauth2, we might want to also use "bearer" where the user would need to use a browser to authenticate and copy the token.
Another possibility would be to have something like this blog where we use info from the settings.json

@name oauth2
POST {{accessTokenUri}}?grant_type=client_credentials&client_id={{clientId}}&client_secret={{clientSecret}}
Content-Type: application/x-www-form-urlencoded

###
GET https://{hostAddress}/api/endpoint HTTP/1.1
Authorization: Bearer {{oauth2.response.body.access_token}}