We looked at service design considerations in the [first part of this blog series](https://konghq.com/blog/service-design-guidelines-with-openapi-and-kong-part-i)first part of this blog series. In this next part, I'd like to share some best practices for API versioning - a topic that comes up quite often with every customer as it is one of the key concerns when implementing [API gateways](https://konghq.com/blog/learning-center/what-is-an-api-gateway)API gateways.

There are two ways to version [RESTful APIs](https://konghq.com/blog/learning-center/what-is-restful-api)RESTful APIs: URI and header-based, as summarized in this [REST API tutorial](https://restfulapi.net/versioning)REST API tutorial. While there may be variations of these strategies (e.g., DNS-based), the focus in this blog will be to show how Kong supports both popular methods. This includes any variations that you may want to apply.

We will keep microservices versioning strategies that utilize other protocols like gRPC, GraphQL, eventing, etc. out of scope for this. Instead, we'll cover the RESTful APIs documented with OpenAPI specification, which remains the most common way to publish and manage APIs with versions today.

## How Do API Versions Work in Kong?

The answer to this is simple: versions are handled by Routes, as illustrated below.

## Real-World Example

Let's take an example of an Order API. You could handle versions in two ways, so I have created three OpenAPI specifications to use in each case using [Insomnia](https://insomnia.rest)Insomnia. The table below captures the versioning style and lifecycle stage, which is supported in both Insomnia and [Kong's Dev Portal](https://konghq.com/kong-konnect#portal)Kong's Dev Portal.

Here is what my Insomnia workspace looks like for Order APIs:

### Order API v1.0

Insomnia offers a design view to provide a preview of OpenAPI specification.

You could deploy the v1.0 API configuration in decK format using the built-in OpenAPI to Kong configuration tooling. Insomnia automatically generates the regular expression for the route/path from the specification, saving you time to focus on implementing your business logic for the Order API.

_format_version: "1.1"
services:
  - name: Ticket_Order_API
    url: http://api.venue1-kongdemo:8000/ticketing
    plugins: []
    routes:
      - tags:
          - OAS3_import
        name: Ticket_Order_API-v1.0_order_id-post
        methods:
          - POST
        paths:
          - /v1.0/order/(?<id>\S+)$
        strip_path: false

### Order API v1.1

Kong configuration for the API in decK format:

_format_version: "1.1"
services:
  - name: Ticket_Order_API
    url: http://api.venue1-kongdemo:8000/ticketing
    plugins: []
    routes:
      - tags:
          - OAS3_import
        name: Ticket_Order_API-v1.1_order_id-post
        methods:
          - POST
        paths:
          - /v1.1/order/(?<id>\S+)$
        strip_path: false

### Order API v1 (versioned by Header)

As you can see in this scenario, the version sends as a header instead of the URI path style in the previous two APIs.

Kong configuration for the API in decK format:

_format_version: "1.1"
services:
  - name: Ticket_Order_API
    url: http://api.venue1-kongdemo:8000/ticketing
    plugins: []
    routes:
      - tags:
          - OAS3_import
        name: Ticket_Order_API-order_id-post
        methods:
          - POST
        paths:
          - /order/(?<id>\S+)$
        strip_path: false

We've seen how you can design your APIs, following [API Guidelines](https://konghq.com/blog/engineering/best-practices-for-api-design-guidelines)API Guidelines, with versions and tags that can be deployed to Kong and managed/viewed within Kong Manager. Next, let's see how you can use these APIs in the Dev Portal.

### Publishing to the Dev Portal

Kong Dev Portal supports content-level permissions management. This serves two primary purposes:

1. - Provide role-based view access to APIs published on the Catalog
2. - Manage multiple versions on the Catalog (e.g., tag with lifecycle stages or hide deprecated or un-used versions)

Here is where you can manage content permissions within the Dev Portal section of Kong Manager:

In the example below, you can specify the view permission for API specifications based on the below levels:

• - Public/Unauthenticated
• - Registered/Authenticated
• - Role-based (Authenticated)

## Implementation Guidelines

Until now, we've focused on designing APIs to handle versions within API specifications. Next, we'll need to route the requests based on the incoming version to the appropriate API implementation (e.g., a microservice). Kong, with its transformer plugins, makes this very simple. Below I list two approaches on how you can route to the upstream (backend API implementation) based on the type of versioning you have within your API specification.

**Approach 1 **- URI-Based Versioning With URL Rewriting Before Routing to Backend Services

[](https://docs.konghq.com/hub/kong-inc/request-transformer-advanced/#template-as-value)[https://docs.konghq.com/hub/kong-inc/request-transformer-advanced/#template-as-value](https://docs.konghq.com/hub/kong-inc/request-transformer-advanced/#template-as-value)https://docs.konghq.com/hub/kong-inc/request-transformer-advanced/#template-as-value

[https://docs.konghq.com/hub/kong-inc/route-transformer-advanced/](https://docs.konghq.com/hub/kong-inc/route-transformer-advanced/)https://docs.konghq.com/hub/kong-inc/route-transformer-advanced/

**Approach 2 **- Header-Based Versioning

## Handling Deprecation

A quick note on handling deprecated APIs as per standard. The [IETF Internet draft](https://tools.ietf.org/html/draft-ietf-httpapi-deprecation-header-01)IETF Internet draft states as below:

You can easily use the [Response Transformer plugin](https://docs.konghq.com/hub/kong-inc/response-transformer-advanced)Response Transformer plugin to signal a specific API is deprecated so the consumer can start taking steps to move to a more recent version of the API.

## Konnect ServiceHub

ServiceHub in Konnect SaaS control plane is a central API repository that acts as a service registry for easy discoverability of APIs. The good news is we have brought versioning as an in-built feature for Service packages.

## Service Packages and Versions

Here is how the same Order API with its three different versions sit within one Service package in Service Hub. Cool, isn't it?

## Migration

Are you thinking, "How could I move between Konnect self-managed and Hybrid SaaS to take advantage of versions in Service package?" Not to worry, with the new deck convert command, released in [decK](https://docs.konghq.com/deck)decK v1.7, you’re now able to convert the configuration between them easily.

## Let Us Know How Your API Versions Turn Out

[Start a Kong Konnect free trial](https://konghq.com/kong-konnect)Start a Kong Konnect free trial or [contact us](https://support.konghq.com/support/s/?_ga=2.220853277.461335063.1619442427-852472749.1605808164)contact us if you have any questions as you're getting set up.

Once you've set up your service design guidelines, you may find these other tutorials helpful:

• - [3 Ways Kong Helps With API Gateway Governance](https://konghq.com/blog/api-gateway-governance)3 Ways Kong Helps With API Gateway Governance
• - [Getting Started with Kong Mesh and Open Policy Agent](https://konghq.com/blog/kong-service-mesh-and-opa-policy)Getting Started with Kong Mesh and Open Policy Agent
• - [Protect Your APIs With Kong Konnect and Fastly (Signal Sciences)](https://konghq.com/blog/kong-konnect-fastly)Protect Your APIs With Kong Konnect and Fastly (Signal Sciences)