From 4fc370e7c71ce5524941b344e34058444f59d4d7 Mon Sep 17 00:00:00 2001 From: Nicolas Ruflin Date: Tue, 10 Sep 2019 13:58:15 +0200 Subject: [PATCH] Update README about API endpoints and query params (#96) Also adding some details about basic architecture / setup. --- README.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 29dc390c92..cd49001c3c 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,24 @@ Endpoints: * `/`: Info about the registry * `/search`: Search for packages. By default returns all the most recent packages available. -* `/package/{name}`: Info about a package -* `/package/{name}.tar.gz`: Download a package +* `/categories`: List of the existing package categories and how many packages are in each category. +* `/package/{name}-{version}`: Info about a package +* `/package/{name}-{version}.tar.gz`: Download a package Examples for each API endpoint can be found here: https://github.com/elastic/integrations-registry/tree/master/docs/api +The `/search` API endpoint has few additional query parameters. More might be added in the future, but for now these are: + +* kibana: Filters out all the packages which are not compatible with the given Kibana version. If it is set to `7.3.1` and + a package requires 7.4, the package will not be returned or an older compatible package will be shown. + 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`. In contrast to the other endpoints, it will return + by default all versions of this package. + +The different query parameters above can be combined, so `?package=mysql&kibana=7.3.0` will return all mysql package versions +which are compatible with `7.3.0`. + ## Package structure The structure of each integration package is standardised. It looks as following: @@ -68,6 +81,19 @@ A full example with the directory structure looks as following: More details about each asset can be found in ASSETS.md +## Architecture + +There are 2 main parts to the integration registry: + +* Generation of package and content +* Serving content through a simple http endpoint + +As much of the endpoints as possible is generated in advance. All package data is pregenerate and is statically served. +The only exceptions here are the `/categories` and `/search` endpoint as they allow query parameters which leads to many +variations and will also get more complex over time. + +`mage build` takes all the packages and generates the content under `public`. The generated content itself is not checked in. + ## Directories * build/packages: Contains all the example integrations packages. These are only example integration packages used for development. Run `mage build` to generate these.