Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.2.x (latest)
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Older Enterprise versions (2.1-2.5)
  • Older OSS versions (2.1-2.5)
  • Archive (pre-2.1)
    • Overview of Kong Gateway
      • Version Support Policy
      • Third Party Dependencies
      • Browser Support
    • Stability
    • Release Notes
      • Services
        • Overview
        • Configure Routes with Expressions
      • Upstreams
      • Plugins
      • Routing Traffic
      • Load Balancing
      • Health Checks and Circuit Breakers
      • Kong Performance Testing
    • Glossary
    • Get Kong
    • Services and Routes
    • Rate Limiting
    • Proxy Caching
    • Key Authentication
    • Load-Balancing
      • Overview
        • Overview
        • Deploy Kong Gateway in Hybrid mode
      • DB-less Deployment
      • Traditional
      • Overview
        • Helm
        • OpenShift with Helm
        • kubectl apply
        • Kubernetes Deployment Options
        • Using docker run
        • Build your own Docker images
        • Amazon Linux
        • Debian
        • Red Hat
        • Ubuntu
      • Running Kong as a non-root user
      • Securing the Admin API
      • Using systemd
      • Start Kong Gateway Securely
      • Programatically Creating Admins
      • Enabling RBAC
      • Overview
      • Download your License
      • Deploy Enterprise License
      • Using the License API
      • Monitor Licenses Usage
      • Default Ports
      • DNS Considerations
      • Network and Firewall
      • CP/DP Communication through a Forward Proxy
        • Configure PostgreSQL TLS
        • Troubleshooting PostgreSQL TLS
    • Kong Configuration File
    • Environment Variables
    • Embedding Kong in Open Resty
    • Serving a Website and APIs from Kong
      • Overview
      • Prometheus
      • StatsD
      • Datadog
      • Overview
      • Writing a Custom Trace Exporter
      • Tracing API Reference
    • Resource Sizing Guidelines
    • Security Update Process
    • Blue-Green Deployments
    • Canary Deployments
    • Clustering Reference
      • Log Reference
      • Dynamic log level updates
      • Customize Gateway Logs
      • Upgrade Kong Gateway 3.x.x
      • Migrate from OSS to Enterprise
    • Overview
      • Overview
      • Metrics
      • Analytics with InfluxDB
      • Analytics with Prometheus
      • Estimate Analytics Storage in PostgreSQL
      • Overview
      • Getting Started
      • Advanced Usage
        • Overview
        • Environment Variables
        • AWS Secrets Manager
        • Google Secrets Manager
        • Hashicorp Vault
        • Securing the Database with AWS Secrets Manager
      • Reference Format
      • Overview
      • Get Started with Dynamic Plugin Ordering
      • Overview
      • Enable the Dev Portal
      • Publish an OpenAPI Spec
      • Structure and File Types
      • Themes Files
      • Working with Templates
      • Using the Editor
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
        • Manage Developers
        • Developer Roles and Content Permissions
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
          • External OAuth2 Support
          • Set up Okta and Kong for External Oauth
          • Set up Azure AD and Kong for External Authentication
        • Manage Applications
        • Theme Editing
        • Migrating Templates Between Workspaces
        • Markdown Rendering Module
        • Customizing Portal Emails
        • Adding and Using JavaScript Assets
        • Single Page App in Dev Portal
        • Alternate OpenAPI Renderer
      • SMTP
      • Workspaces
      • Helpers CLI
      • Portal API Documentation
    • Audit Logging
    • Keyring and Data Encryption
    • Workspaces
    • Consumer Groups
    • Event Hooks
    • Configure Data Plane Resilience
    • About Control Plane Outage Management
      • Overview
      • Install the FIPS Compliant Package
      • FIPS 140-2 Compliant Plugins
    • Overview
    • Enable Kong Manager
      • Services and Routes
      • Rate Limiting
      • Proxy Caching
      • Authentication with Consumers
      • Load Balancing
      • Overview
      • Create a Super Admin
      • Workspaces and Teams
      • Reset Passwords and RBAC Tokens
      • Basic Auth
        • Configure LDAP
        • LDAP Service Directory Mapping
        • Configure OIDC
        • OIDC Authenticated Group Mapping
      • Sessions
        • Overview
        • Enable RBAC
        • Add a Role and Permissions
        • Create a User
        • Create an Admin
    • Networking Configuration
    • Workspaces
    • Create Consumer Groups
    • Sending Email
    • Overview
    • File Structure
    • Implementing Custom Logic
    • Plugin Configuration
    • Accessing the Data Store
    • Storing Custom Entities
    • Caching Custom Entities
    • Extending the Admin API
    • Writing Tests
    • (un)Installing your Plugin
      • Overview
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.jwe
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.tracing
      • kong.vault
      • kong.websocket.client
      • kong.websocket.upstream
      • Go
      • Javascript
      • Python
      • Running Plugins in Containers
      • External Plugin Performance
    • Overview
        • Overview
        • OpenID Connect with Curity
        • OpenID Connect with Azure AD
        • OpenID Connect with Google
        • OpenID Connect with Okta
        • OpenID Connect with Auth0
        • OpenID Connect with Cognito
      • Authentication Reference
      • Allow Multiple Authentication Plugins
    • Rate Limiting Plugin
      • Add a Body Value
    • GraphQL
      • gRPC Plugins
      • Configure a gRPC service
    • Overview
    • Information Routes
    • Health Routes
    • Tags
    • Debug Routes
    • Services
    • Routes
    • Consumers
    • Plugins
    • Certificates
    • CA Certificates
    • SNIs
    • Upstreams
    • Targets
    • Vaults
    • Keys
    • Licenses
    • Workspaces
    • RBAC
    • Admins
    • Developers
    • Consumer Groups
    • Event Hooks
    • Keyring and Data Encryption
    • Audit Logs
    • kong.conf
    • Injecting Nginx Directives
    • CLI
    • Key Management
    • Performance Testing Framework
    • Router Expressions Language
    • FAQ

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • What is a service
  • What is a route
  • Prerequisites
  • Managing services
  • Managing routes
Kong Gateway
3.2.x (latest)
  • Home
  • Kong Gateway
  • Get Started
  • Services and Routes

Services and Routes

Kong Gateway administrators work with an object model to define their desired traffic management policies. Two important objects in that model are services and routes. Services and routes are configured in a coordinated manner to define the routing path that requests and responses will take through the system.

The high level overview below shows requests arriving at routes and being forward to services, with responses taking the opposite pathway:

Services and routes

What is a service

In Kong Gateway, a service is an abstraction of an existing upstream application. Services can store collections of objects like plugin configurations, and policies, and they can be associated with routes.

When defining a service, the administrator provides a name and the upstream application connection information. The connection details can be provided in the url field as a single string, or by providing individual values for protocol, host, port, and path individually.

Services have a one-to-many relationship with upstream applications, which allows administrators to create sophisticated traffic management behaviors.

What is a route

A route is a path to a resource within an upstream application. Routes are added to services to allow access to the underlying application. In Kong Gateway, routes typically map to endpoints that are exposed through the Kong Gateway application. Routes can also define rules that match requests to associated services. Because of this, one route can reference multiple endpoints. A basic route should have a name, path or paths, and reference an existing service.

You can also configure routes with:

  • Protocols: The protocol used to communicate with the upstream application.
  • Hosts: Lists of domains that match a route
  • Methods: HTTP methods that match a route
  • Headers: Lists of values that are expected in the header of a request
  • Redirect status codes: HTTPS status codes
  • Tags: Optional set of strings to group routes with

See Routes for a description of how Kong Gateway routes requests.

Managing services and routes

The following tutorial walks through managing and testing services and routes using the Kong Gateway Admin API. Kong Gateway also offers other options for configuration management including Kong Kong Konnect and decK.

In this section of the tutorial, you will complete the following steps:

  • Create a service pointing to the Mockbin API, which provides testing facilities for HTTP requests and responses.
  • Define a route by providing a URL path that will be available to clients on the running Kong Gateway.
  • Use the new Mockbin service to echo a test request, helping you understand how Kong Gateway proxies API requests.

Prerequisites

This chapter is part of the Get Started with Kong series. For the best experience, it is recommended that you follow the series from the beginning.

The introduction, Get Kong, includes tool prerequisites and instructions for running a local Kong Gateway.

If you haven’t completed the Get Kong step already, complete that before proceeding.

Managing services

  1. Creating services

    To add a new service, send a POST request to Kong Gateway’s Admin API /services route:

    curl -i -s -X POST http://localhost:8001/services \
      --data name=example_service \
      --data url='http://mockbin.org'
    

    This request instructs Kong Gateway to create a new service mapped to the upstream URL http://mockbin.org.

    In our example, the request body contained two strings:

    • name: The name of the service
    • url : An argument that populates the host, port, and path attributes of the service

    If your request was successful, you will see a 201 response header from Kong Gateway confirming that your service was created and the response body will be similar to:

    {
      "host": "mockbin.org",
      "name": "example_service",
      "enabled": true,
      "connect_timeout": 60000,
      "read_timeout": 60000,
      "retries": 5,
      "protocol": "http",
      "path": null,
      "port": 80,
      "tags": null,
      "client_certificate": null,
      "tls_verify": null,
      "created_at": 1661346938,
      "updated_at": 1661346938,
      "tls_verify_depth": null,
      "id": "3b2be74e-335b-4f25-9f08-6c41b4720315",
      "write_timeout": 60000,
      "ca_certificates": null
    }
    

    Fields that are not explicitly provided in the create request are automatically given a default value based on the current Kong Gateway configuration.

  2. Viewing service configuration

    When you create a service, Kong Gateway assigns it a unique id as shown in the response above. The id field, or the name provided when creating the service, can be used to identify the service in subsequent requests. This is the service URL and takes the form of /services/{service name or id}.

    To view the current state of a service, make a GET request to the service URL.

    curl -X GET http://localhost:8001/services/example_service
    

    A successful request will contain the current configuration of your service in the response body and will look something like the following snippet:

    {
      "host": "mockbin.org",
      "name": "example_service",
      "enabled": true,
      ...
    }
    
  3. Updating services

    Existing service configurations can be updated dynamically by sending a PATCH request to the service URL.

    To dynamically set the service retries from 5 to 6, send this PATCH request:

    curl --request PATCH \
      --url localhost:8001/services/example_service \
      --data retries=6
    

    The response body contains the full service configuration including the updated value:

    {
      "host": "mockbin.org",
      "name": "example_service",
      "enabled": true,
      "retries": 6,
      ...
    }
    
  4. Listing services

    You can list all current services by sending a GET request to the base /services URL.

    curl -X GET http://localhost:8001/services
    

The Admin API documentation provides the full service update specification.

Managing routes

  1. Creating routes

    Routes define how requests are proxied by Kong Gateway. You can create a route associated with a specific service by sending a POST request to the service URL.

    Configure a new route on the /mock path to direct traffic to the example_service service created earlier:

    curl -i -X POST http://localhost:8001/services/example_service/routes \
      --data 'paths[]=/mock' \
      --data name=example_route
    

    If the route was successfully created, the API returns a 201 response code and a response body like this:

    {
      "paths": [
        "/mock"
      ],
      "methods": null,
      "sources": null,
      "destinations": null,
      "name": "example_route",
      "headers": null,
      "hosts": null,
      "preserve_host": false,
      "regex_priority": 0,
      "snis": null,
      "https_redirect_status_code": 426,
      "tags": null,
      "protocols": [
        "http",
        "https"
      ],
      "path_handling": "v0",
      "id": "52d58293-ae25-4c69-acc8-6dd729718a61",
      "updated_at": 1661345592,
      "service": {
        "id": "c1e98b2b-6e77-476c-82ca-a5f1fb877e07"
      },
      "response_buffering": true,
      "strip_path": true,
      "request_buffering": true,
      "created_at": 1661345592
    }
    
  2. Viewing route configuration

    Like services, when you create a route, Kong Gateway assigns it a unique id as shown in the response above. The id field, or the name provided when creating the route, can be used to identify the route in subsequent requests. The route URL can take either of the following forms:

    • /services/{service name or id}/routes/{route name or id}
    • /routes/{route name or id}

    To view the current state of the example_route route, make a GET request to the route URL:

    curl -X GET http://localhost:8001/services/example_service/routes/example_route
    

    The response body contains the current configuration of your route:

    {
      "paths": [
        "/mock"
      ],
      "methods": null,
      "sources": null,
      "destinations": null,
      "name": "example_route",
      "headers": null,
      "hosts": null,
      "preserve_host": false,
      "regex_priority": 0,
      "snis": null,
      "https_redirect_status_code": 426,
      "tags": null,
      "protocols": [
        "http",
        "https"
      ],
      "path_handling": "v0",
      "id": "189e0a57-205a-4f48-aec6-d57f2e8a9985",
      "updated_at": 1661347991,
      "service": {
        "id": "3b2be74e-335b-4f25-9f08-6c41b4720315"
      },
      "response_buffering": true,
      "strip_path": true,
      "request_buffering": true,
      "created_at": 1661347991
    }
    
  3. Updating routes

    Like services, routes can be updated dynamically by sending a PATCH request to the route URL.

    Tags are an optional set of strings that can be associated with the route for grouping and filtering. You can assign tags by sending a PATCH request to the services endpoint and specifying a route.

    Update the route by assigning it a tag with the value tutorial:

    curl --request PATCH \
      --url localhost:8001/services/example_service/routes/example_route \
      --data tags="tutorial"
    

    The above example used the service and route name fields for the route URL.

    If the tag was successfully applied, the response body will contain the following JSON value:

    ...
    "tags":["tutorial"]
    ...
    
  4. Listing routes

    The Admin API also supports the listing of all routes currently configured:

    curl http://localhost:8001/routes
    

    This request returns an HTTP 200 status code and a JSON response body object array with all of the routes configured on this Kong Gateway instance. Your response should look like the following:

    {
      "next": null,
      "data": [
        {
          "paths": [
            "/mock"
          ],
          "methods": null,
          "sources": null,
          "destinations": null,
          "name": "example_route",
          "headers": null,
          "hosts": null,
          "preserve_host": false,
          "regex_priority": 0,
          "snis": null,
          "https_redirect_status_code": 426,
          "tags": [
            "tutorial"
          ],
          "protocols": [
            "http",
            "https"
          ],
          "path_handling": "v0",
          "id": "52d58293-ae25-4c69-acc8-6dd729718a61",
          "updated_at": 1661346132,
          "service": {
            "id": "c1e98b2b-6e77-476c-82ca-a5f1fb877e07"
          },
          "response_buffering": true,
          "strip_path": true,
          "request_buffering": true,
          "created_at": 1661345592
        }
      ]
    }
    

The Admin API documentation has the full specification for managing route objects.

Proxy a request

Kong is an API Gateway, it takes requests from clients and routes them to the appropriate upstream application based on a the current configuration. Using the service and route that was previously configured, you can now access https://mockbin.org/ using http://localhost:8000/mock.

By default, Kong Gateway’s Admin API listens for administrative requests on port 8001, this is sometimes referred to as the control plane. Clients use port 8000 to make data requests, and this is often referred to as the data plane.

Mockbin provides a /requests resource which will echo back to clients information about requests made to it. Proxy a request through Kong Gateway to the /requests resource:

curl -X GET http://localhost:8000/mock/requests

You should see a response similar to the following:

{
  "startedDateTime": "2022-08-24T13:44:28.449Z",
  "clientIPAddress": "172.19.0.1",
  "method": "GET",
  "url": "http://localhost/requests",
  "httpVersion": "HTTP/1.1",
  "cookies": {},
  "headers": {
    "host": "mockbin.org",
    "connection": "close",
    "accept-encoding": "gzip",
    "x-forwarded-for": "172.19.0.1,98.63.188.11, 162.158.63.41",
    "cf-ray": "73fc85d999f2e6b0-EWR",
    "x-forwarded-proto": "http",
    "cf-visitor": "{\"scheme\":\"http\"}",
    "x-forwarded-host": "localhost",
    "x-forwarded-port": "80",
    "x-forwarded-path": "/mock/requests",
    "x-forwarded-prefix": "/mock",
    "user-agent": "curl/7.79.1",
    "accept": "*/*",
    "cf-connecting-ip": "00.00.00.00",
    "cdn-loop": "cloudflare",
    "x-request-id": "1dae4762-5d7f-4d7b-af45-b05720762878",
    "via": "1.1 vegur",
    "connect-time": "0",
    "x-request-start": "1661348668447",
    "total-route-time": "0"
  },
  "queryString": {},
  "postData": {
    "mimeType": "application/octet-stream",
    "text": "",
    "params": []
  },
  "headersSize": 588,
  "bodySize": 0
}

Previous Get Kong
Next Rate Limiting
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023