Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarification regarding reflecting rest parameters in OpenAPI specification #3448

Closed
SachinAkash01 opened this issue Nov 13, 2023 · 28 comments
Closed

Clarification regarding reflecting rest parameters in OpenAPI specification #3448

SachinAkash01 opened this issue Nov 13, 2023 · 28 comments
Labels
Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk

Comments

@SachinAkash01
Copy link

SachinAkash01 commented Nov 13, 2023 •
edited
Loading

Hi Team!

I am working with Ballerina OpenAPI tool, specifically utilizing rest parameters in the path of a resource function, where they act as an array. For example:

resource function get albums/[string... title]() {}

This allows us to send a request like:
GET albums/title1/title2/title3

In the resulting URL, these parameters are concatenated with %2F (encoded value for /), and it looks like:
http://{hostName}:{port}/albums/title1%2Ftitle2%2Ftitle3

I am seeking guidance on how to accurately reflect this behavior in the OpenAPI specification. Specifically, I would like to understand how to handle parameter serialization using the style and explode attributes in this scenario.

Could you provide insights or examples on how to properly represent this scenario in the OpenAPI specification. Is there a proper way to do that?

#1459
@commonism
Copy link
Contributor

https://spec.openapis.org/oas/v3.1.0#style-values
Examples for titles = ["no 1","best of"]
Array Query Parameters can be encoded as Simple (no%201,best%20of) Label (.no%201.best%20of) or Matrix (;titles=no%201,best%20of) none of which match your encoding.

Explode true for matrix ends up with ;titles=no%201;titles=best%20of

import sys

import httpx

from aiopenapi3 import OpenAPI

spec = """
openapi: "3.0.0"
info:
  title: titles
  version: 1.0.0
  description: https://github.com/OAI/OpenAPI-Specification/issues/3448

servers:
  - url: http://127.0.0.1/api

paths:
  /albums/{titles}:
    parameters:
    - name: titles
      description: ""
      required: True        
      in: path
      style: matrix
      explode: true
      schema:
        type:
          array
        items:
          type: string
      
    get:
      operationId: albums
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: array
                items: 
                  type: string
"""

def test_loader_format(httpx_mock):
    titles = ["no 1","best of"]
    httpx_mock.add_response(headers={"Content-Type": "application/json"}, status_code=200, json=titles)
    api = OpenAPI.loads("http://127.0.0.1/openapi.yaml", spec, session_factory=httpx.Client)
    api._.albums(parameters={"titles":titles})
    request = httpx_mock.get_requests()[-1]
    print(request.url)
    return None

@github-actions github-actions bot added the No recent activity The issue has not been updated in 7 days. label Nov 22, 2023
@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

20 similar comments
@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@lornajane lornajane removed the No recent activity The issue has not been updated in 7 days. label Nov 22, 2023
@lornajane
Copy link
Contributor

Hi everyone, sorry about the noise on this pull request, we have some new automation and apparently it is still settling in! I think I've removed the label that was causing this behaviour, please accept our apologise and proceed as normal.

@baywet Could you take a look at this please? I just added the author feedback label today and it immediately started adding the recent-activity thing, repeatedly 😱

@github-actions github-actions bot added the No recent activity The issue has not been updated in 7 days. label Nov 22, 2023
@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

1 similar comment
@github-actions GitHub Actions
Copy link
Contributor

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

@lornajane lornajane removed the No recent activity The issue has not been updated in 7 days. label Nov 22, 2023
@baywet
Copy link
Contributor

baywet commented Nov 22, 2023

@lornajane sorry about the confusion this caused here. Here is a PR to address the many issues #3457

@SachinAkash01
Copy link
Author

https://spec.openapis.org/oas/v3.1.0#style-values Examples for titles = ["no 1","best of"] Array Query Parameters can be encoded as Simple (no%201,best%20of) Label (.no%201.best%20of) or Matrix (;titles=no%201,best%20of) none of which match your encoding.

Explode true for matrix ends up with ;titles=no%201;titles=best%20of

import sys

import httpx

from aiopenapi3 import OpenAPI

spec = """
openapi: "3.0.0"
info:
  title: titles
  version: 1.0.0
  description: https://github.com/OAI/OpenAPI-Specification/issues/3448

servers:
  - url: http://127.0.0.1/api

paths:
  /albums/{titles}:
    parameters:
    - name: titles
      description: ""
      required: True        
      in: path
      style: matrix
      explode: true
      schema:
        type:
          array
        items:
          type: string
      
    get:
      operationId: albums
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: array
                items: 
                  type: string
"""

def test_loader_format(httpx_mock):
    titles = ["no 1","best of"]
    httpx_mock.add_response(headers={"Content-Type": "application/json"}, status_code=200, json=titles)
    api = OpenAPI.loads("http://127.0.0.1/openapi.yaml", spec, session_factory=httpx.Client)
    api._.albums(parameters={"titles":titles})
    request = httpx_mock.get_requests()[-1]
    print(request.url)
    return None

Thank you @commonism for the prompt response and the provided example. I've reviewed the example with explode-style encoding and explode set to true. However, it still doesn't quite match with the behavior I'm observing with Ballerina rest parameters in the resource path.

After having some discussions, we decided to map this scenario in another way using wildcard path in OAS. You can refer the issue I have created regarding this here: ballerina-platform/ballerina-library/issues/5816

@handrews handrews added the Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk label Jan 24, 2024
@handrews
Copy link
Member

This also falls under #2653 and is likewise being addressed through the Moonwalk project (see links in that issue's last comment).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Moved to Moonwalk Issues that can be closed or migrated as being addressed in Moonwalk
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@commonism @lornajane @handrews @baywet @SachinAkash01