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

Update README and OpenAPI to include prerelease parameter #794

Merged
merged 4 commits into from
Feb 24, 2022
Merged

Update README and OpenAPI to include prerelease parameter #794

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
75fcfaf
Update README for deprecation of experimental flag
jsoriano Feb 23, 2022
dd940d8
Add prerelease param to openapi
jsoriano Feb 23, 2022
443222b
Fix description
jsoriano Feb 23, 2022
fb4f01d
Clarify what is a prerelease version
jsoriano Feb 24, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,18 @@ The `/search` API endpoint has few additional query parameters. More might be ad
By default this endpoint always returns only the newest compatible package.
* `category`: Filters the package by the given category. Available categories can be seend when going to `/categories` endpoint.
* `package`: Filters by a specific package name, for example `mysql`. Returns the most recent version.
* `all`: This can be set to true to list all package versions. This is set to `false` by default.
* `experimental`: This can be set to true to list packages considered to be experimental. This is set to `false` by default.
* `all`: This can be set to `true` to list all package versions. This is set to `false` by default.
* `prerelease`: This can be set to `true` to list prerelease versions of packages. This is set to `false` by default.
Copy link
Member

@andrewkroh andrewkroh Feb 23, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you define what "prerelease versions" means. Like say that it means versions <1.0 and packages using the deprecated beta and experimental release tags (IIRC).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added description. The registry fully relies on semantic versioning to decide if the version of a package is a prerelease, release tags are not considered. This is why it is important to have consistency between release tags and versions till we fully sunset versions that rely on release tags.

* `experimental` (deprecated): This can be set to `true` to list packages considered to be experimental. This is set to `false` by default.

The different query parameters above can be combined, so `?package=mysql&kibana.version=7.3.0` will return all mysql package versions
which are compatible with `7.3.0`.

The `/categories` API endpoint has two additional query parameters.

* `experimental`: This can be set to true to list categories from experimental packages. This is set to `false` by default.
* `include_policy_templates`: This can be set to true to include categories from policy templates. This is set to `false` by default.
* `prerelease`: This can be set to `true` to list prerelease versions of packages. This is set to `false` by default.
* `experimental` (deprecated): This can be set to `true` to list categories from experimental packages. This is set to `false` by default.
* `include_policy_templates`: This can be set to `true` to include categories from policy templates. This is set to `false` by default.

## Package structure

Expand Down
11 changes: 11 additions & 0 deletions openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ paths:
description: List of the existing package categories and how many packages are in each category
parameters:
- $ref: '#/components/parameters/experimentalPackageParam'
- $ref: '#/components/parameters/prereleasePackageParam'
/search:
get:
summary: Search packages
Expand Down Expand Up @@ -85,6 +86,7 @@ paths:
name: package
description: 'Filters by a specific package name, for example mysql. In contrast to the other endpoints, it will return by default all versions of this package.'
- $ref: '#/components/parameters/experimentalPackageParam'
- $ref: '#/components/parameters/prereleasePackageParam'
'/package/{package}/{version}':
get:
summary: GET package info
Expand Down Expand Up @@ -369,7 +371,16 @@ components:
name: experimental
in: query
required: false
deprecated: true
description: Set to true to also list experimental packages
schema:
type: boolean
default: false
prereleasePackageParam:
name: prerelease
in: query
required: false
description: Set to true to also list prerelease versions of packages
schema:
type: boolean
default: false