Adapt API to REST conventions #86
Description
Background
The extensions registry is the authoritative source of truth for information about k6 extensions (strictly speaking, it contains “modules” because it also has information about k6 itself). It contains multiple metadata that can be used to filter according to different criteria.
The content of the registry is exposed using an API described in https://registry.k6.io/.
This API exposes different endpoints that can be used to retrieve collections of modules according to different filters, like tier and compliance grade. For tier and grade, the API allowed filtering extensions that had "at-least" a given tier or grade.
It also offers metrics regarding the extensions on the collection.
Problem
The existing API does not adhere to the conventions of RESTful APIs, and there are inconsistencies with respect to which resources are available for different filters.
Proposal
- Adopt REST-style naming conventions for resource collections
- Consider the modules list, catalog, and metrics sub-resources in a collection
- Offer the same sub-resources (catalog, list of modules, metrics) consistently for different collections
- Remove the 'at-least' filters. For tier, this is no longer necessary as there are only two, while for grades there's no use case.
Proposed changes
| Curent | Proposed | Return |
|---|---|---|
| GET/catalog.json | GET/catalog.json | List all modules/extensions in json format |
| GET module/{module}/extension.json | GET modules/{module}/extension.json | Get details for a module in json format |
| GET /module/{module}/badge.svg | GET modules/{module}/badge.svg | Get the badge for a module |
| GET /module/{module}/grade.svg | GET modules/{module}/grade.svg | Get grade badge for module |
| GET /metrics.json | GET /metrics.json | Get metrics in JSON format |
| GET /metrics.txt | GET /metrics.txt | Get metrics in Prometheus format |
| GET /tier/{tier}.json | GET /tiers/{tier}/modules.json | modules for a tier |
| GET /tier/{tier}-catalog.json | GET /tiers/{tier}/catalog.json | catalog for a tier |
| GET /tier/{tier}-metrics.json | GET /tiers/{tier}/metrics.json | Metrics for a tier |
| GET /tier/at-least/{tier}.json | -- remove -- | Modules with at least a given tier |
| -- N/A -- | GET /grade/{grade}/catalog.json | catalog for a grade |
| GET /grade/{grade}.json | GET /grades/{grade}/modules.json | Modules for a grade |
| -- N/A -- | GET /grades/{grade}/metrics.json | Modules for a grade json format |
| -- N/A -- | GET /grades/{grade}/metrics.txt | Modules for a grade prometheus format |
| GET /grade/at-least/{grade}.json | -- remove -- | Modules with at least a given grade |