Step 4 - Publish API v1.0

Before publishing our first API, it’s important to understand what the DevOps (or API Dev) team provided us.

They provided us an OpenAPI spec file (OASv3) via SwaggerHub. You can consult version 1.0 here: https://app.swaggerhub.com/apis/F5EMEASSA/API-Sentence/1.0

../../../_images/OASv1.0.png

Note

This is version 1.0 of the API, and in this version, as you can notice, the Colors micro-service is not yet available. This means that with this spec file we will publish the API Sentence application without the Colors micro-service (e.g. a sample sentence might look like calm mouse of the mountain).


Steps to publish version 1.0 of the API

Create the API Definition

  1. In NGINX Controller, select Home (the NGINX logo on the top left corner) -> Services -> APIs -> Create API Version:

    1. First, you will need to create an API Definition. To do so, click on CREATE NEW under the API Definition box (which is empty):
      • Name: api-sentence
      • Click Submit
    2. Select OpenAPI Specification -> Copy and paste specification text.
    3. Copy and paste the YAML content from https://app.swaggerhub.com/apis/F5EMEASSA/API-Sentence/1.0
    4. Verify that the version set by NGINX Controller is 1.0. This information is extracted from the spec file.
    5. Click Next. You will notice NGINX Controller imported all the PATH and METHODS resources from the spec file.
    6. Click Submit

    Note

    At this moment in the configuration process, NGINX Controller knows the API paths and methods, but does not know where to proxy the traffic to.

  2. Click on the created API Definition. On the right side menu you can see the version and the number of resources:

    ../../../_images/api-definition.png

Create a Published API for v1.0

  1. Let’s now publish version 1.0 of the API. Click on Add Published API. Use the following values:

    • Name: api-sentence-v1

    • Click Next

    • Environment: env_prod

    • App: api-sentence-app (we automatically created this for you behind the scenes for this lab)

    • Gateways: apigw

    • Click Next

      ../../../_images/deployment.png
  2. In Routing, we will create one component per micro-service:
    1. Click Add New to create a new component for the Generator micro-service:
      1. Name: cp-generator

      2. Click Next

      3. In Workload Groups:
        • Name: wl-generator

        • In Backend Workload URIs:

          • URI: http://10.1.20.8:31200

            Note

            This URL is the FQDN and the NodePort used by the micro-service running in the K3S.

          • Click Done

        • Click Done

      4. Click Next

        ../../../_images/component-generator.png
      5. Click Submit

    2. We now have to replicate the same steps for each other of the micro-services

      List of all micro-services and their component configuration
      Name Workload Group Name Backend Workload URI
      cp-generator wl-generator http://10.1.20.8:31200
      cp-locations wl-locations http://10.1.20.8:31103
      cp-animals wl-animals http://10.1.20.8:31101
      cp-adjectives wl-adjectives http://10.1.20.8:31100
    3. You should now have a list of 4 empty components.

    4. On the left side, under Unrouted you can see every API Path imported from the OAS spec file.

    5. Drag and drop each unrouted API Path (shown as a resource here) to the corresponding component.

      ../../../_images/routing.png
  3. Click Submit

../../../_images/published-api-v1.0.png

Note

API v1.0 is now published, and we can now check if it is working as expected.


Test the v1.0 API deployment

Steps:

  1. RDP to the Win10 VM (user/user).

  2. Open the Edge Browser and select the Random Name Generator bookmark.

  3. The Frontend will display a sentence with Words coming from the Generator.

    ../../../_images/frontend-nocolors.png

    Note

    As you can notice, there are no Colors in the sentence as we didn’t deploy and publish the Color micro-service. This lab’s traffic flow is shown below, and as you can see, the web traffic is not passing through the API Gateway yet. Instead, all the web traffic is routed through the k8s ingress.

    ../../../_images/api-workflow1.png
  4. Open Postman and select the API Sentence Generator v1 and v2 collection.

  5. Send a request with the GET Locations call. The FQDN is different from the Frontend web app, and reaches the API Gateway directly. The API Gateway will in turn route the request to the Locations micro-service, and will return all the entries (all the words).

    [
        {
            "id": 1,
            "name": "valley"
        },
        {
            "id": 2,
            "name": "park"
        },
        {
            "id": 3,
            "name": "mountain"
        }
    ]
    
  6. Send a request with the GET a Sentence from Generator call. This request will request the Generator micro-service to get one word per Word micro-service.

    {
       "adjectives": "calm",
       "animals": "whale",
       "locations": "park"
    }
    

    Note

    The above results will generate the sentence calm whale of the park in the Frontend application.

Warning

Congrats! You just published your first API using NGINX Controller and NGINX Plus as an API Gateway!