# API Definition ## Configuration ```toml # API definition # Warning: Enabling API will expose Traefik's configuration. # It is not recommended in production, # unless secured by authentication and authorizations [api] # Name of the related entry point # # Optional # Default: "traefik" # entryPoint = "traefik" # Enable Dashboard # # Optional # Default: true # dashboard = true # Enable debug mode. # This will install HTTP handlers to expose Go expvars under /debug/vars and # pprof profiling data under /debug/pprof/. # Additionally, the log level will be set to DEBUG. # # Optional # Default: false # debug = true ``` For more customization, see [entry points](/configuration/entrypoints/) documentation and the examples below. ## Web UI ![Web UI Providers](/img/web.frontend.png) ![Web UI Health](/img/traefik-health.png) ## Security Enabling the API will expose all configuration elements, including sensitive data. It is not recommended in production, unless secured by authentication and authorizations. A good sane default (but not exhaustive) set of recommendations would be to apply the following protection mechanism: * _At application level:_ enabling HTTP [Basic Authentication](#authentication) * _At transport level:_ NOT exposing publicly the API's port, keeping it restricted over internal networks (restricted networks as in https://en.wikipedia.org/wiki/Principle_of_least_privilege). ## API | Path | Method | Description | |-----------------------------------------------------------------|------------------|-------------------------------------------| | `/` | `GET` | Provides a simple HTML frontend of Traefik | | `/cluster/leader` | `GET` | JSON leader true/false response | | `/health` | `GET` | JSON health metrics | | `/api` | `GET` | Configuration for all providers | | `/api/providers` | `GET` | Providers | | `/api/providers/{provider}` | `GET`, `PUT` | Get or update provider (1) | | `/api/providers/{provider}/backends` | `GET` | List backends | | `/api/providers/{provider}/backends/{backend}` | `GET` | Get backend | | `/api/providers/{provider}/backends/{backend}/servers` | `GET` | List servers in backend | | `/api/providers/{provider}/backends/{backend}/servers/{server}` | `GET` | Get a server in a backend | | `/api/providers/{provider}/frontends` | `GET` | List frontends | | `/api/providers/{provider}/frontends/{frontend}` | `GET` | Get a frontend | | `/api/providers/{provider}/frontends/{frontend}/routes` | `GET` | List routes in a frontend | | `/api/providers/{provider}/frontends/{frontend}/routes/{route}` | `GET` | Get a route in a frontend | <1> See [Rest](/configuration/backends/rest/#api) for more information. !!! warning For compatibility reason, when you activate the rest provider, you can use `web` or `rest` as `provider` value. But be careful, in the configuration for all providers the key is still `web`. ### Address / Port You can define a custom address/port like this: ```toml defaultEntryPoints = ["http"] [entryPoints] [entryPoints.http] address = ":80" [entryPoints.foo] address = ":8082" [entryPoints.bar] address = ":8083" [ping] entryPoint = "foo" [api] entryPoint = "bar" ``` In the above example, you would access a regular path, dashboard, and health-check as follows: * Regular path: `http://hostname:80/path` * Dashboard: `http://hostname:8083/` * Ping URL: `http://hostname:8082/ping` In the above example, it is _very_ important to create a named dedicated entry point, and do **not** include it in `defaultEntryPoints`. Otherwise, you are likely to expose _all_ services via that entry point. ### Custom Path You can define a custom path like this: ```toml defaultEntryPoints = ["http"] [entryPoints] [entryPoints.http] address = ":80" [entryPoints.foo] address = ":8080" [entryPoints.bar] address = ":8081" # Activate API and Dashboard [api] entryPoint = "bar" dashboard = true [file] [backends] [backends.backend1] [backends.backend1.servers.server1] url = "http://127.0.0.1:8081" [frontends] [frontends.frontend1] entryPoints = ["foo"] backend = "backend1" [frontends.frontend1.routes.test_1] rule = "PathPrefixStrip:/yourprefix;PathPrefix:/yourprefix" ``` ### Authentication You can define the authentication like this: ```toml defaultEntryPoints = ["http"] [entryPoints] [entryPoints.http] address = ":80" [entryPoints.foo] address=":8080" [entryPoints.foo.auth] [entryPoints.foo.auth.basic] users = [ "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/", "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0", ] [api] entrypoint="foo" ``` For more information, see [entry points](/configuration/entrypoints/) . ### Provider call example ```shell curl -s "http://localhost:8080/api" | jq . ``` ```json { "file": { "frontends": { "frontend2": { "routes": { "test_2": { "rule": "Path:/test" } }, "backend": "backend1" }, "frontend1": { "routes": { "test_1": { "rule": "Host:test.localhost" } }, "backend": "backend2" } }, "backends": { "backend2": { "loadBalancer": { "method": "drr" }, "servers": { "server2": { "weight": 2, "URL": "http://172.17.0.5:80" }, "server1": { "weight": 1, "url": "http://172.17.0.4:80" } } }, "backend1": { "loadBalancer": { "method": "wrr" }, "circuitBreaker": { "expression": "NetworkErrorRatio() > 0.5" }, "servers": { "server2": { "weight": 1, "url": "http://172.17.0.3:80" }, "server1": { "weight": 10, "url": "http://172.17.0.2:80" } } } } } } ``` ### Cluster Leadership ```shell curl -s "http://localhost:8080/cluster/leader" | jq . ``` ```shell < HTTP/1.1 200 OK < Content-Type: application/json; charset=UTF-8 < Date: xxx < Content-Length: 15 ``` If the given node is not a cluster leader, an HTTP status of `429-Too-Many-Requests` will be returned. ```json { // current leadership status of the queried node "leader": true } ``` ### Health ```shell curl -s "http://localhost:8080/health" | jq . ``` ```json { // Traefik PID "pid": 2458, // Traefik server uptime (formated time) "uptime": "39m6.885931127s", // Traefik server uptime in seconds "uptime_sec": 2346.885931127, // current server date "time": "2015-10-07 18:32:24.362238909 +0200 CEST", // current server date in seconds "unixtime": 1444235544, // count HTTP response status code in realtime "status_code_count": { "502": 1 }, // count HTTP response status code since Traefik started "total_status_code_count": { "200": 7, "404": 21, "502": 13 }, // count HTTP response "count": 1, // count HTTP response "total_count": 41, // sum of all response time (formated time) "total_response_time": "35.456865605s", // sum of all response time in seconds "total_response_time_sec": 35.456865605, // average response time (formated time) "average_response_time": "864.8016ms", // average response time in seconds "average_response_time_sec": 0.8648016000000001, // request statistics [requires --api.statistics to be set] // ten most recent requests with 4xx and 5xx status codes "recent_errors": [ { // status code "status_code": 500, // description of status code "status": "Internal Server Error", // request HTTP method "method": "GET", // request hostname "host": "localhost", // request path "path": "/path", // RFC 3339 formatted date/time "time": "2016-10-21T16:59:15.418495872-07:00" } ] } ``` ## Metrics You can enable Traefik to export internal metrics to different monitoring systems. ```toml [api] # ... # Enable more detailed statistics. [api.statistics] # Number of recent errors logged. # # Default: 10 # recentErrors = 10 # ... ``` | Path | Method | Description | |------------|---------------|-------------------------| | `/metrics` | `GET` | Export internal metrics |