Step 6 - Publish API v3.0

The API Dev has now modified an existing endpoint. They modified the Locations micro-service in order to add a new JSON object for the coordinates of the location.

To do so, they:

• Created a new micro-service container image, with a new tag (v3.0): registry.gitlab.com/sentence-application/locations/volterra:v3.0
• Created a new version (v3.0) of the OAS spec file: https://app.swaggerhub.com/apis/F5EMEASSA/API-Sentence/3.0

As you can see in the OAS file v3.0, the /locations endpoint has a new JSON object:

Warning

Modifying an existing API endpoint means the API v2.0 will break. Any mobile application or API client using the /locations endpoint will receive an error if we don’t create a dedicated version for this new API version.

Steps to publish API v3.0

Deploy the new Locations v3.0 micro-service in k8s

Let’s deploy the Locations v3.0 micro-service!

1. SSH (or Web) to the Docker (k3s + Rancher + ELK) VM.

2. Run the following kubectl command in order to deploy the Locations micro-service and its k8s service:

   sudo su
   kubectl apply -f /home/ubuntu/k3s/attributs_locations_v3.yaml -n api
   

   Note

   As you can notice, this micro-service is deployed in the same NameSpace as the other Words micro-services (api), and the previous version of the Locations micro-service is still there, because it’s currently used by clients.

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

4. Check in Rancher (admin/admin) that the new Deployment has been successful (both the Deployment and Service)

   

Note

Great! So now, the Location micro-service is running with 2 versions (v1.0) and (v3.0). Both versions are published through NodePort on 2 different ports:

• Port 31103 for Locations v1/v2
• Port 31303 for Locations v3

Create version 3.0 for the existing API Definition

1. Connect to NGINX Controller, and enter in the APIs configuration section (Top left Nginx Logo menu -> Services -> APIs)

2. Select your API Definition api-sentence, and on the top right corner select Add Version.

   

3. Select OpenAPI Specification -> Copy and paste specification text.

4. Copy and paste the v3.0 OAS YAML content from https://app.swaggerhub.com/apis/F5EMEASSA/API-Sentence/3.0

   Note

   You can notice the version is automatically set to 3.0

   

5. Click Submit

Note

You should now see on the right sidebar the new 3.0 version

It is time to publish this new version of the API for a sample of clients (early access, beta …)

Publish version 3.0 of the API

Note

This new API version will listen on a specific path (/v3/) in order to differentiate the Production API (v2.0) from this Early Access API (v3.0).

1. Select the 3.0 API Definition, click on Add Published API. Use the following values:

   

2. Start by setting the Base Path. This is the path to differentiate the various Published APIs. Set it to /v3 and check the box Strip Base Path so that the API Gateway does not use the path to connect to the backend micro-services.

   

   • Name: api-sentence-v3

   • Click Next.

   • Set the Environment, the App and the Gateway as with version 1.0.

     

   • Click Next

3. Configure the Routing as with version 1.0 except for the location component which now routes the traffic to a different micro-service in k8s (listening on port 31303 instead of 31103 for v1.0).

   List of all micro-services and their component configuration.

   Name	Workload Group Name	Backend Workload URI
   cp-generator-v3	wl-generator-v3	http://10.1.20.8:31200
   cp-locations-v3	wl-locations-v3	http://10.1.20.8:31303
   cp-animals-v3	wl-animals-v3	http://10.1.20.8:31101
   cp-adjectives-v3	wl-adjectives-v3	http://10.1.20.8:31100
   cp-colors-v3	wl-colors-v3	http://10.1.20.8:31102

4. Drag and drop each Path resource to the corresponding component.

   

5. Click Submit

6. Check if your Published API is green. If not, address any errors and re-submit.

   Note

   The flag can take some time to become GREEN (due to resources limitations in UDF). If the flag is RED, wait few seconds, and re-submit your changes (refresh the page too).

   

Test the v3.0 (and v2.0) API deployments

Steps:

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

2. Open Postman and the API Sentence Generator v3 collection.

3. Send a request with the GET Colors v3 call, and check the PATH. Notice that the PATH starts with /v3. It means the request is being routed by version 3 of the API Definition.

   [
       {
           "id": 1,
           "name": "red"
       },
       {
           "id": 2,
           "name": "blue"
       },
       {
           "id": 3,
           "name": "green"
       },
       {
           "name": "black",
           "id": 4
       },
       {
           "name": "yellow",
           "id": 5
       }
   ]
   

4. Send a request with the GET Locations v3 call. This is the updated version of the location micro-service running in k8s.

   [
       {
           "id": 2,
           "name": "park",
           "coordinates": [
               -142.28261413,
               53.28261413
           ]
       },
       {
           "id": 3,
           "name": "mountain",
           "coordinates": [
               -110.28261413,
               31.28261413
           ]
       },
       {
           "name": "valley",
           "coordinates": [
               -123.10664756,
               49.28261413
           ],
           "id": 4
       }
   ]
   

   Note

   As you can see, we now have a new JSON object coordinates, coming from the updated location micro-service.

5. Send a request with the GET Locations call in the API Sentence Generator v1 and v2 collection in order to test that version 2.0 is still up and running.

   [
       {
           "id": 1,
           "name": "valley"
       },
       {
           "id": 2,
           "name": "park"
       },
       {
           "id": 3,
           "name": "mountain"
       }
   ]
   

Warning

Congrats! You published v3.0 of your API and it’s correctly being routed to the new locations micro-service! Furthermore, version 2.0 is still available for any “current” clients. Only the Early Access clients querying the /v3 path get access to this new API.