Cloud-native API Administration with Red Hat 3scale API Management

Procedure 2.3. Instructions

1. Use the 3scale Toolbox CLI to extract the USER_KEY and STAGING_DOMAIN environment variables to use during this exercise.

   1. Extract the user_key into a USER_KEY environment variable.

      To extract the user_key get the application ID for the applications_versions_app.

      [student@workstation ~]$ APP_ID=$(3scale application list 3scale-tenant -o json \
         | jq '.[] | select(.name == "applications_versions_app") | .id')

      Use the APP_ID application ID to get the user_key value.

      [student@workstation ~]$ USER_KEY=$(3scale application \
        show 3scale-tenant $APP_ID -o json \
        | jq -r '.user_key')

   2. Extract the staging domain into a STAGING_DOMAIN environment variable.

      [student@workstation ~]$ STAGING_DOMAIN=$(3scale proxy-config \
        show 3scale-tenant applications_versions sandbox -o json \
        | jq -r '.content.proxy.staging_domain')

   3. Verify that the previous steps correctly assigned the STAGING_DOMAIN and USER_KEY environment variables.

      [student@workstation ~]$ echo $STAGING_DOMAIN; echo $USER_KEY
      applications-versions-3scale-apicast-staging.apps.ocp4.example.com
      987f7abce12aaf49a8c297793bf44893

      Note

      Your USER_KEY will differ from the one listed here.

2. Compare versions v1 and v2 to verify that there is a breaking change in the books-api API. Only version v1 is publicly accessible. To test v2 you must log in to RHOCP as the developer user and execute a curl command within the cluster.

   1. Test public access to the books resource in the applications_versions product to verify that only version v1 is accessible.

      [student@workstation ~]$ curl -s \
        "https://$STAGING_DOMAIN/v1/books?user_key=$USER_KEY" | jq
      [
        {
          "authorName": "Mary Shelley",
          "title": "Frankenstein",
          "copies": 10,
          "year": 1818
        },
        ...output omitted...
      ]

      Send a request for version v2 of the books resource.

      [student@workstation ~]$ curl -s \
        "https://$STAGING_DOMAIN/v2/books?user_key=$USER_KEY"; echo
      No Mapping Rule matched

      The response No Mapping Rule matched indicates that the resource is not publicly accessible for v2.

   2. To verify that v2 is actually deployed within the cluster, log in to RHOCP as the developer user. Then use the cluster pod curl-pod to query the v2 of the books resource by using the FQDN for the books-api service.

      Issue the login command to log into RHOCP.

      [student@workstation ~]$ oc login \
        -u=developer -p=redhat --server=https://api.ocp4.example.com:6443
      Logged into "https://api.ocp4.example.com:6443" as "developer" using existing credentials.
      ...output omitted...

      Execute a curl command from within the cluster to verify that v2 is deployed and that the books resource contains a breaking change.

      [student@workstation ~]$ oc exec curl-pod -n applications-versions \
        -- curl -s \
       "http://books-api.applications-versions.svc.cluster.local/api/v2/books" |jq
      
      [
        {
          "title": "Frankenstein",
          "author": {
            "name": "Mary Shelley",
            "birthYear": 1797
          },
          "year": 1818,
          "copies": 10
        },
        ...output omitted...
      ]

      The version v2 replaced authorName with the author object. This is a backward incompatible change and must be published under a new version to avoid breaking existing client code.

3. Navigate to the 3scale Admin Portal and create a backend called books_backend_v2. Set the backend URL to point to the service version v2 by using the http://books-api.applications-versions.svc.cluster.local:80/api/v2/books URL.

   1. Using a web browser, log in to the 3Scale Admin Portal as the admin user. The portal is located at https://3scale-admin.apps.ocp4.example.com.

   2. From the top pane drop-down menu, select Backends to view the list of backends.

   3. Create a backend for the v2 by clicking Create Backend, providing the following values, and submitting the form. Leave all other fields as their default values.

      Field	Value
      Name	books_backend_v2
      Private Base URL	http://books-api.applications-versions.svc.cluster.local:80/api/v2

4. Associate books_backend_v2 backend with the applications_versions product.

   1. From the top pane drop-down menu, click Products, and then click the applications_versions product.

   2. Navigate to the list of backends associated with the product by selecting Integration → Backends. Associate a backend with the product by clicking Add Backend.

      Select books_backend_v2 as the backend, provide the unique path /v2, and submit the form.

      This causes a path rewrite in the handling of the request. It eliminates /v2 from the request path and proceeds to use the backend base URL, which is http://books-api.applications-versions.svc.cluster.local/api/v2.

      Table 2.3. 3scale Request Translation

      Public URL	Private URL
      https://applications-versions-3scale-apicast-staging.apps.ocp4.example.com/v2/books	http://books-api.applications-versions.svc.cluster.local/api/v2/books

      
      

5. Use the 3scale Toolbox CLI to create a new metric hits_v2 to count the number of requests to v2.

   [student@workstation ~]$ 3scale metric create \
     3scale-tenant applications_versions hits_v2
   Created metric id: 11. Disabled: false

6. To allow public access to v2 create a mapping rule for the pattern /v2 and assign it the metric hits_v2.

   1. Navigate to the list of mapping rules associated with the product by selecting Integration → Mapping Rules.

   2. Create a mapping rule for the applications_versions product by clicking Create Mapping Rule, providing the following values, and submitting the form. Leave all other fields as their default values.

      Field	Value
      Verb	GET
      Pattern	/v2
      Method or Metric to increment	Select Metric, then select hits_v2

7. Promote and test the product configuration.

   1. Promote the applications_versions product configuration to the staging environment by using the 3scale Toolbox CLI.

      Use the proxy-config command with the deploy subcommand to promote to staging.

      [student@workstation ~]$ 3scale proxy-config deploy \
        3scale-tenant applications_versions
      {
        "service_id": 3,
        "endpoint": "https://applications-versions-3scale-apicast-production.apps.ocp4.example.com:443",
        "api_backend": "http://books-api.applications-versions.svc.cluster.local:80/api/v1",
      ...output omitted...

      To promote to production you can use the proxy-config command with the promote subcommand instead.

   2. Verify that v2 is publicly accessible by sending a request to the books resource.

      [student@workstation ~]$ curl -s \
        "https://$STAGING_DOMAIN/v2/books?user_key=$USER_KEY" | jq
      [
        {
          "title": "Frankenstein",
          "author": {
            "name": "Mary Shelley",
            "birthYear": 1797
          },
          "year": 1818,
          "copies": 10
        },
        ...output omitted...
      ]

8. In a command-line terminal, run the /scripts/gen-load.sh script in the DO240-apps repository to generate traffic under v1 and v2. Increase the hit count on v1 by 5 and the hit count on v2 by 10.

   [student@workstation ~]$ ~/DO240-apps/scripts/gen-load.sh \
     5 "https://$STAGING_DOMAIN/v1/books?user_key=$USER_KEY"
   5/5 completed requests to https://applications-versions-3scale-apicast-staging.apps.ocp4.example.com/v1/books

   [student@workstation ~]$ ~/DO240-apps/scripts/gen-load.sh \
     10 "https://$STAGING_DOMAIN/v2/books?user_key=$USER_KEY"
   10/10 completed requests to https://applications-versions-3scale-apicast-staging.apps.ocp4.example.com/v2/books

9. Review the endpoint metrics within the 3scale Admin Portal and verify that v2 has 5 more requests than v1.

   1. In the Admin Portal, navigate to Analytics → Traffic.

   2. Select metric Hits used by v1 by clicking Hits (hits). Note the number to compare it with v2

   3. Select metric hits_v2 used by v2 by clicking hits_v2 (hits_v2). Note the resulting total in the graph. This number should be 5 units higher than the number for v1.