mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-21 00:26:23 +03:00
62 lines
4.5 KiB
Markdown
62 lines
4.5 KiB
Markdown
# CNCF Landscape API reference
|
||
|
||
## What the interface is
|
||
|
||
`https://landscape.cncf.io` is a generated static site. The public API is a set of JSON files produced by the `cncf/landscape2` build system, not a query service with server-side search, pagination, or an API root. The API implementation is maintained in [`landscape2`'s API builder](https://github.com/cncf/landscape2/blob/main/crates/cli/src/build/api.rs).
|
||
|
||
Use the generated API as the default application-facing interface. Keep the retrieval time and endpoint in any decision artifact because the data is a rebuildable snapshot.
|
||
|
||
## Endpoints
|
||
|
||
| Purpose | Endpoint |
|
||
|---|---|
|
||
| CNCF project records | `https://landscape.cncf.io/api/projects/all.json` |
|
||
| Project record count | `https://landscape.cncf.io/api/projects/count.json` |
|
||
| One project record | `https://landscape.cncf.io/api/projects/<id>.json` |
|
||
| All CNCF member records | `https://landscape.cncf.io/api/members/all.json` |
|
||
| Member record count | `https://landscape.cncf.io/api/members/count.json` |
|
||
| End-user member records | `https://landscape.cncf.io/api/members/end-users.json` |
|
||
| Category and subcategory slices | `https://landscape.cncf.io/api/categories/<category>/<subcategory>/all.json` |
|
||
|
||
The API also emits category count and `all.json` routes. The exact normalized path should be discovered from the `id`, category, or subcategory values in the current response rather than guessed. The bundled tool avoids most path construction by retrieving the project/member collection and filtering locally.
|
||
|
||
Project IDs from `projects/all.json` are the safe input for the per-project route. Do not derive an ID from a display name when the API has already supplied one.
|
||
|
||
## Project fields
|
||
|
||
Project records commonly include:
|
||
|
||
- `name`, `id`, `description`, `summary`, `homepage_url`, `logo_url`, and category/subcategory;
|
||
- CNCF lifecycle fields such as `maturity`, `accepted_at`, and annual-review URLs/dates;
|
||
- `oss`, `country`, and project or CNCF links;
|
||
- `repositories`, whose records can include `url`, `primary`, `stars`, `contributors`, `languages`, `license`, and `latest_release`.
|
||
|
||
Fields are generated data, not a versioned schema contract. Treat absent, `null`, and empty values as distinct evidence states. A missing field means “not established by this response,” not “false.”
|
||
|
||
Member records are organizational records. They are useful for identifying ecosystem or end-user context, but they are not interchangeable with project records and CNCF membership is not an endorsement or a suitability score.
|
||
|
||
## Query strategy
|
||
|
||
1. Start with `projects/all.json` for technology discovery.
|
||
2. Apply local filters with `scripts/landscape_query.py` so the result is bounded and reproducible.
|
||
3. Fetch per-project records for finalists using the returned `id`.
|
||
4. Verify implementation, compatibility, security, governance, release, and operations claims against the project’s own current sources.
|
||
5. Use `members/all.json` or `members/end-users.json` only when the decision specifically needs ecosystem context.
|
||
|
||
Prefer the normalized `/api/` records over `/data/full.json`. The latter is a richer build artifact containing GitHub and Crunchbase enrichment and may expose fields with different stability or reuse considerations. Use it only when a clearly identified question cannot be answered by the normalized API, and record that choice.
|
||
|
||
## Failure behavior and transport caveats
|
||
|
||
- No API key is required for the public JSON routes observed by this skill.
|
||
- A missing or unknown route can fall through to the single-page application and return HTML with a successful status. Check `Content-Type` before parsing; the bundled tool fails closed on non-JSON responses.
|
||
- The site does not advertise permissive cross-origin headers on the API responses observed during research. Prefer the bundled CLI or another server-side fetch for automation rather than assuming a browser hosted on another origin can call it.
|
||
- There is no stable API discovery document. If a route is not listed here or generated by the current source, probe it read-only and inspect the response before documenting it.
|
||
- Do not report current counts or status when the request failed. Say what endpoint failed and what evidence remains available.
|
||
|
||
## Primary sources
|
||
|
||
- [CNCF Landscape](https://landscape.cncf.io/)
|
||
- [`cncf/landscape`](https://github.com/cncf/landscape), the source-data repository
|
||
- [`cncf/landscape2`](https://github.com/cncf/landscape2), the static-site generator
|
||
- [Landscape API builder](https://github.com/cncf/landscape2/blob/main/crates/cli/src/build/api.rs)
|