Path segment variable with visible name?

[s303]

Looks like there is no way to render a parameter with visible name not as a query parameter.

For example: I have a commits (/commits) resource with page and size query parameters. And I would like to have ability to filter commits by project, and I would like to have it as an optional path parameter with name, like /project/windows95/commits. Is it possible?

Maybe some form of "form-style path operator" ({/project}) could be introduced? Like:

FORMAT: 1A
# Sample API
## Read commits [GET /{/project}/commits{?page,size}]
+ Parameters
  + page: 1 (number)
  + size: 1 (optional, number)
  + project: `windows95` (optional, string)
+ Response 200 (application/json)

That will be rendered as: /project/windows95/commits?page=1

[w-vi]

Hi @sniff

## Read commits [GET /{project}/commits{?page,size}]

+ Parameters
    + page: 1 (number)
    + size: 1 (optional, number)
    + project: `windows95` (optional, string)

+ Response 200 (application/json)

is exactly what you ask for if I am reading correctly.

Another example with parameters https://apiblueprint.org/documentation/examples/07-parameters.html

[s303]

@w-vi No, it does not. This will add only parameter value to URL (windows95) without parameter name (project) itself.

Your example will be rendered as /windows95/commits?page=1 if project is present, and I would like to have /project/windows95/commits?page=1.

I don't want to describe two methods for with 100% same parameters (page, size...) like:

FORMAT: 1A
# Sample API
## Read commits [GET /commits{?page,size}]
+ Parameters
  + page: 1 (number)
  + size: 1 (optional, number)
+ Response 200 (application/json)
## Read commits for project [GET /project/{projectName}/commits{?page,size}]
+ Parameters
  + page: 1 (number)
  + size: 1 (optional, number)
  + projectName: `windows95` (optional, string)
+ Response 200 (application/json)

[FranklinYu]

How about shared parameter section:

FORMAT: 1A

# Sample API

## Commit collection [/commits{?page,size}]

+ Parameters
    + page: 1 (number)
    + size: 1 (optional, number)

### Read commits [GET /commits{?page,size}]

+ Response 200 (application/json)

### Read commits for project [GET /project/{projectName}/commits{?page,size}]

+ Parameters
    + projectName: `windows95` (optional, string)
+ Response 200 (application/json)

[pksunkara]

You can inherit parameters for an action from a resource currently.

[s303]

@franklinyu Could be an option, but it still requires to duplicate descriptions and Responses for both sections