github.com/muhammadn/cortex@v1.9.1-0.20220510110439-46bb7000d03d/docs/proposals/api_design.md (about)

     1  ---
     2  title: "HTTP API Design"
     3  linkTitle: "HTTP API Design"
     4  weight: 1
     5  slug: http-api-design
     6  ---
     7  
     8  - Author: @jtlisi
     9  - Reviewers: @pracucci, @pstibrany, @khaines, @gouthamve
    10  - Date: March 2020
    11  - Status: Accepted
    12  
    13  ## Overview
    14  
    15  The purpose of this design document is to propose a set of standards that should be the basis of the Cortex HTTP API. This document will outline the current state of the Cortex http api and describe limitations that result from the current approach. It will also outline a set of paradigms on how http routes should be created within Cortex.
    16  
    17  ## Current Design
    18  
    19  As things currently stand, the majority of HTTP API calls exist under the `/api/prom` path prefix. This prefix is configurable. However, since this prefix is shared between all the modules which leads to conflicts if the Alertmanager is attempted to be run as as part of the single binary (#1722).
    20  
    21  ## Proposed Design
    22  
    23  ### Module-Based Routing
    24  
    25  Cortex incorporates three separate APIs: Alertmanager, Prometheus, and Cortex. Each of these APIs should use a separate route prefix that accurately describes the API. Currently, all of the api calls in Cortex reside under the configured http prefix. Instead the following routing tree is proposed:
    26  
    27  #### `/prometheus/*`
    28  
    29  Under this path prefix, Cortex will act as a Prometheus web server. It will host all of the required Prometheus api endpoints. For example to query cortex the endpoint `/prometheus/api/v1/query_range` will be used.
    30  
    31  #### `/alertmanager/*`
    32  
    33  Under this path prefix, Cortex will act as a Alertmanager web server. In this case, it will forward requests to the alertmanager and support the alertmanager API. This means for a user to access their Alertmanager UI, they will use the `/alertmanager` path of cortex.
    34  
    35  #### `/api/v1/*` -- The cortex API will exist under this path prefix.
    36  
    37  - `/push`
    38  - `/chunks`
    39  - `/rules/*`
    40  
    41  | Current             | Proposed          |
    42  | ------------------- | ----------------- |
    43  | `/api/prom/push`    | `/api/v1/push`    |
    44  | `/api/prom/chunks`  | `/api/v1/chunks`  |
    45  | `/api/prom/rules/*` | `/api/v1/rules/*` |
    46  
    47  
    48  #### Service Endpoints
    49  
    50  A number of endpoints currently exist that are not under the `/api/prom` prefix that provide basic web interfaces and trigger operations for cortex services. These endpoints will all be placed under a url with their service name as a prefix if it is applicable.
    51  
    52  | Current               | Proposed                           |
    53  | --------------------- | ---------------------------------- |
    54  | `/status`             | `/multitenant-alertmanager/status` |
    55  | `/config`             | `/config`                          |
    56  | `/ring`               | `/ingester/ring`                   |
    57  | `/ruler_ring`         | `/ruler/ring`                      |
    58  | `/compactor/ring`     | `/compactor/ring`                  |
    59  | `/store-gateway/ring` | `/store-gateway/ring`              |
    60  | `/ha-tracker`         | `/distributor/ha_tracker`          |
    61  | `/all_user_stats`     | `/distributor/all_user_stats`      |
    62  | `/user_stats`         | `/distributor/user_stats`          |
    63  | `/flush`              | `/ingester/flush`                  |
    64  | `/shutdown`           | `/ingester/shutdown`               |
    65  
    66  ### Path Versioning
    67  
    68  Cortex will utilize path based versioning similar to both Prometheus and Alertmanager. This will allow future versions of the API to be released with changes over time.
    69  
    70  ### Backwards-Compatibility
    71  
    72  The new API endpoints and the current http prefix endpoints can be maintained concurrently. The flag to configure these endpoints will be maintained as `http.prefix`. This will allow us to roll out the new API without disrupting the current routing schema. The original http prefix endpoints can maintained indefinitely or be phased out over time. Deprecation warnings can be added to the current API either when initialized or utilized. This can be accomplished by injecting a middleware that logs a warning whenever a legacy API endpoint is used.
    73  
    74  In cases where Cortex is run as a single binary, the Alertmanager module will only be accesible using the new API.
    75  
    76  ### Implementation
    77  
    78  This will be implemented by adding an API module to the Cortex service. This module will handle setting up all the required HTTP routes with Cortex. It will be designed around a set of interfaces required to fulfill the API. This is similar to how the `v1` Prometheus API is implemented.
    79  
    80  ### Style
    81  
    82  * All new paths will utilize `_` instead of `-` for their url to conform with Prometheus and its use of the underscore in the `query_range` endpoint. This applies to all operations endpoints. Component names in the path can still contain dashes. For example: `/store-gateway/ring`.