# APISnoop Design Plan

This document proposes semi-significant updates to apisnoop.cncf.io to improve its navigation and usability.

Below is a list of proposals, how it will change the current apisnoop.cncf.io site, and the intention behind the change.

## Proposal: URL routes are patterned after kubernetes releases, from 1.15 to latest

Currently, the routes are patterned after the storage bucket and job that holds the test run.

For example: right now test runs for 1.17 are held in storage bucket `ci-kubernetes-e2e-gce-cos-k8sstable1-default`, with our data set used on site pulling from job #1273740400212840454

This means you can view coverage for 1.17 by visiting:
`apisnoop.cncf.io/ci-kubernetes-e2e-gce-cos-k8sstable1-default/1273740400212840454`
You can see the stable core endpoints for this release with:
`apisnoop.cncf.io/ci-kubernetes-e2e-gce-cos-k8sstable1-default/1273740400212840454/stable/core`

A benefit of this is you can map test-grid and prow results to APISnoop results to see where we are getting our data. The downside is that it is unintuitive to know which bucket/job combination ties to a particular release, and won't be consistent as time goes on--as releases continue, k8sstable1-default will soon represent 1.18 or 1.19.

### Our Change
To see coverage for 1.17 you would visit:
`apisnoop.cncf.io/1.17/`
To see stable core endpoints:
`apisnoop.cncf.io/1.17/stable/core`

In addition, you can see the latest test run with:
`apisnoop.cncf.io/latest`

There would still be a link to the data-set we use for a release beneath the releases title, it just would not be baked into the url.

We would limit ourselves to the minor version of kubernetes, not distinguishing between patches. In other words, we would hold data for 1.18, but that may be 1.18.3 or 1.18.5.

## Proposal: Front Page centers on coverage sunburst

Currently, the top of the page shows a coverage over time graph, indicating the testing percentage and conformance-tested percentage for the stable endpoints. Below this is a sunburst showing the full coverage of that release. By clicking on any data point in the coverage over time graph, you switch to that particular release, showing in the sunburst below.

Frankly, this is a total UI misstep. It is not clear that you can visit past releases by clicking on data points in the coverage over time graph. It's also cognitively dissonant as the numbers in the two graphs are not consistent. Over time is focused only on stable endpoints, while the sunburst shows the full api, and so the 'total coverage' will be exteremly different numbers.

### Our Change

The Sunburst returns as primary focus of main page and all release pages. The coverage over time graph is removed entirely from this view, moving to a separate `/conformance-progress` route.

The landing page defaults to the latest release (= the same release as`/latest`). there will be an explicit dropdown to switch between past releases.

## Proposal: Conformance Progress Charts moves to a separate page

We have been working on a set of charts for conformance progress, showing how many conformant endpoints there've been from 1.9 to today. One of these charts lives on the front page, the others are not yet public.

### Our Change

We have a route at `/conformance-progress` that display a set of infographics focused on stable endpoints and their conformance coverage. A variation of the current coverage over time graph would live here, along with a set of new ones showing things like:

- new endpoints per release, and how many came in with tests.
- new endpoints per release, and how many are still untested
- total percentage of conformance coverage per release from 1.9 to today.

These charts would be largely static, e.g. clicking on a data point would not act as a navigation link, but may show a short list of additonal info about that particular point in time.

## New About Page added with links to further documentation

Currently, there is some documentation in our apisnoop repo, but it is not as explicit or easy-to-find as it shoudl be. This leaves too many questions about how the site operates.

### Our Change

We have an about page that gives a short overview of APISnoop and how it gathers it data.

It would include:
- update schedule for apisnoop
- the data source
- definitions and further documentation for conformance, and e2e tests.
- links to more documentation around kubernetes testing and our work.

## Navigation Links added to top bar of APISnoop

We currently have a green band at the top of the page, with the APISnoop logo in the top corner, but not much else.

### Our Change

There are now links to the new parts of the site.
So navigation would be:
- home
- conformance progress
- about apisnoop