Skip to content

Commit

Permalink
change up the endpoints
Browse files Browse the repository at this point in the history 
Signed-off-by: Travis <longoria.public@gmail.com>
  • Loading branch information
@elbandito
elbandito committed Dec 10, 2020
1 parent 500c4ae commit 128103d
Showing 1 changed file with 92 additions and 31 deletions.
123 changes: 92 additions & 31 deletions text/0000-buildpack-registry-search-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
[meta]: #meta
- Name: Buildpack Registry Search API
- Start Date: 2020-11-11
- Author(s): elbandito
- Author(s): @elbandito
- RFC Pull Request: (leave blank)
- CNB Pull Request: (leave blank)
- CNB Issue: (leave blank)
Expand Down Expand Up @@ -36,54 +36,110 @@ As the CNB project makes progress towards supporting a centralized Buildpack Reg
# What it is
[what-it-is]: #what-it-is

An external API service that exposes endpoints for retrieving buildpack metadata. Initially, I envision this service providing a few GET endpoints to support plain text query searches, and individual buildpack data retrieval.
An external API service that exposes endpoints for retrieving buildpack metadata. Initially, I envision this service providing a few GET endpoints to support plain text query searches, and individual buildpack data retrieval. The API endpoints will be versioned, and follow OpenAPI and/or Json Schema/API standards.

### Supported Endpoints

- **GET /search?query=text**
- **GET /search?matches=text**

Retrievs all the buildpacks that satisfy the search query. If the response contains more than 20 buildpacks, pagination will be used. For example:
```
$ curl https://registry.buildpacks.io/search?query=projectriff
$ curl https://registry.buildpacks.io/v1/search?matches=projectriff
```
```json
[
{
"ns":"projectriff",
"name":"command-function",
"version":"1.4.1",
"yanked":false,
"addr":"gcr.io/projectriff/command-function@sha256:99f9054abb73635a9b251b61d3627a8ff86508c767f9d691c426d45e8758596f"
"latest": {
"description": "The Command Function Buildpack is a Cloud Native Buildpack V3 that provides riff Command Function Invoker to functions",
"license": "MIT",
"ns":"projectriff",
"name":"command-function",
"version": "1.4.1",
"yanked":false,
"addr":"gcr.io/projectriff/command-function@sha256:99f9054abb73635a9b251b61d3627a8ff86508c767f9d691c426d45e8758596f"
},
"versions": {
"1.4.1": {
"link": "https://registry.buildpacks.io/v1/buildpacks/projectriff/command-function/1.4.1"
},
"1.3.9": {
"link": "https://registry.buildpacks.io/v1/buildpacks/projectriff/command-function/1.3.9"
}
}
},
{
"ns":"projectriff",
"name":"java-function",
"version":"1.4.1",
"yanked":false,
"addr":"gcr.io/projectriff/java-function@sha256:5eabea8f7b2c09074ec196fe0c321006fb5ad8f282cc918520286d8a0007196f"
"latest": {
"description": "The Java Function Buildpack is a Cloud Native Buildpack V3 that provides riff Java Function Invoker to functions",
"license": "MIT",
"ns":"projectriff",
"name":"java-function",
"version": "1.4.3",
"yanked":false,
"addr":"gcr.io/projectriff/java-function@sha256:5eabea8f7b2c09074ec196fe0c321006fb5ad8f282cc918520286d8a0007196f"
},
"versions": {
"1.4.3": {
"link": "https://registry.buildpacks.io/v1/buildpacks/projectriff/java-function/1.4.3"
},
"1.3.9": {
"link": "https://registry.buildpacks.io/v1/buildpacks/projectriff/java-function/1.3.9"
}
}
},
{
"latest": {
"description": "The Node Function Buildpack is a Cloud Native Buildpack V3 that provides riff Node Function Invoker to functions",
"license": "MIT",
"ns":"projectriff",
"name":"node-function",
"version": "1.5.6",
"yanked":false,
"addr":"gcr.io/projectriff/node-function@sha256:194298b826c15bb079c59aed99968d7678a6e1f7a882c9d7f61811e0990717ba"
},
"versions": {
"1.5.6": {
"link": "https://registry.buildpacks.io/v1/buildpacks/projectriff/node-function/1.5.6"
},
"1.3.9": {
"link": "https://registry.buildpacks.io/v1/buildpacks/projectriff/node-function/1.3.9"
}
}
}
]
```

- **GET /buildpacks/:ns/:name**

Retrieves metadata for a specific buildpack.
```
$ curl https://registry.buildpacks.io/v1/buildpacks/projectriff/command-function
```
```json
{
"latest": {
"description": "The Command Function Buildpack is a Cloud Native Buildpack V3 that provides riff Command Function Invoker to functions",
"license": "MIT",
"ns":"projectriff",
"name":"node-function",
"version":"1.4.1",
"name":"command-function",
"version": "1.4.1",
"yanked":false,
"addr":"gcr.io/projectriff/node-function@sha256:194298b826c15bb079c59aed99968d7678a6e1f7a882c9d7f61811e0990717ba"
"addr":"gcr.io/projectriff/command-function@sha256:99f9054abb73635a9b251b61d3627a8ff86508c767f9d691c426d45e8758596f"
},
{
"ns":"projectriff",
"name":"streaming-http-adapter",
"version":"1.4.0",
"yanked":false,
"addr":"gcr.io/projectriff/streaming-http-adapter@sha256:b202d9ec203e882ee7e3c599d9e867617f909c8b6123e4ce942af47db6e58c45"
"versions": {
"1.4.1": {
"link": "https://registry.buildpacks.io/buildpacks/v1/projectriff/command-function/1.4.1"
},
"1.3.9": {
"link": "https://registry.buildpacks.io/buildpacks/v1/projectriff/command-function/1.3.9"
}
}
]
```
}

- **GET /buildpacks/:ns/:name**
- **GET /buildpacks/:ns/:name/:version**

Retrieves metadata for a specific buildpack. This response *could* contain more detailed data e.g. download metrics.
Retrieves metadata for a specific buildpack version (`:version` must be a semver or `latest`). This response *may* contain more metadata e.g. download metrics. Since `description` and `license` can change between different versions, it should therefore ONLY be included for each specific buildpack version.
```
$ curl https://registry.buildpacks.io/buildpacks/projectriff/command-function
$ curl https://registry.buildpacks.io/buildpacks/v1/projectriff/command-function/1.4.1
```
```json
{
Expand All @@ -104,12 +160,16 @@ In the initial implementation, we can take advantage of the existing [registry](

Each time the local repository has been updated via `git pull`, buildpack data will be processed/normalized into a single JSON object, where plain text searches can be used against it. Fields in this JSON object will be re-indexed as searchable fields, which will be compared against the search text during the retrieval algorithm.

Search fields will include `ns`, `name`, `license`, and `yanked`.
Search fields will include `ns`, and `name`.

In addition, a server process will expose endpoints and handle incoming request for the GET endpoints mentioned earlier. For search requests, the text will be extracted from the `query` query parameter and used to search against the normalized buildpacks index. Results will be added to the server response, as a list of JSON objects.

*Note: Initially, the Distribution Team maintainers can manage this service, and could even set-up a pager (but only best effort, and during working hours). In the future, we maybe able to extend this to other verified project contributors.

### Future Work

- Query fields will be broken-up into separate, finer grained fields e.g. `ns`, `name`, and `yarnked`.

# Drawbacks
[drawbacks]: #drawbacks

Expand Down Expand Up @@ -167,5 +227,6 @@ Why should we *not* do this?

- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC?

1. A registry dashboard e.g. web-based application with design considerations that provides a clean UX for discovering Buildpacks.
2. Adding metrics e.g. number of downloads, issues, etc. or any other metadata to the buildpack.
1. A registry dashboard e.g. web-based application with design considerations that provides a clean UX for discovering buildpacks.
2. Adding metrics e.g. number of downloads, issues, etc.
3. Adding additional metadata in either/both the buildpack or buildpack version response objects

0 comments on commit 128103d

Please sign in to comment.