Swagger Editor - Small Image

Exposing FIS-based Service as a 3scale API – My Learning Journey Part 1

Introduction

In my previous article, I created a reusable FIS demo. Today, I am going to show you how to use the 3scale API Management Platform to create an API for the FIS ‘products’ service. By doing so, the service gains non-functional capabilities including access control, rate limits, analytics, activeDocs, billing & payment, etc. Starting my learning journey with 3scale, I decided to set up my own self-managed 3scale gateway and use an online swagger editor to create a swagger spec to document the service. During my journey, I ran into some gotchas, mysterious behaviours, and problems that were eventually overcome. Overall, it was a good learning experience although frustrating at times. I am sharing my learning journey with you pictorially in this article. Hope you’ll find it useful.

Prerequisites

To follow along and deploy you API, you need the following:

  • an Openshift cluster – the development environment is an Openshift cluster set up using ‘oc cluster up’. I have set up one at home which is accessible from the Internet. You may set up such an environment on your PC using a VM or in the cloud. If you want to set one up, have a look at my other article here.
  • The FIS Reusable Demo deployed on your Openshift cluster. Details on how to do this can be found here.

Setting Up an API (Service)

Here are the steps that are required to define a 3scale API or service. Daniel already covered them but I want to elaborate on them based on my learning experience. The steps are:

  1. Login to 3scale
  2. Select APIs→Create Serviceselecting APIcast (3scale-managed) and API key (user_key)Create ServiceAlthough I said earlier that my target is to use a self-managed gateway , I specified 3scale-managed gateway here to use a 3scale-managed gateway here because I have to test the endpoint of my service via 3scale now. I have to use the 3scale-managed gateway.
  1. Use the latest APIcast and define a new method and a mapping ruleNote that by choosing 3scale-managed gateway earlier, the Staging and Production Public Base URLs have been populated automatically for you.
    Staging and Production URLs
    Staging and Production URLs

    And after you have defined a mapping rule, save it using the ‘Update & test Staging Environment’ button. When you look at the curl statement, you will not see the actual user_key as in the following screenshot. You will have to complete steps 4 and 5 (which result in the creation of a user_key for your API) and come back here before you will get the actual user_key. Once the user_key has been filled in, you can copy the curl command to test out your API.

    user_key In Curl Command
    user_key In Curl Command
  2. Select APIs-> Application Plan→Create Application PlanFill in the Name and System name for your Application plan.

    Application Plan
    Application Plan
  3. Unless you are modifying an existing API or this is the first API you define, you have to create an Application after creating an Application Plan otherwise a user_key will not be generated. Select Developers then developer (group) then Applications. This is the gotcha part. It is easy to create an Application Plan but where to create an application is not quite intuitive. It requires going through several screens before you can create one. It took me sometime to figure it out.
    Create Application Page
    Create Application Page
    Create Application
    Create Application

    Select products_basic (the application plan created earlier) and give the Application a name. I called mine products_app

  4. Select APIs then shipping-products then edit APICast configuration over several screens.You should now see that the user-key has been populated in the curl command at the bottom. Click ‘Update & Test Staging Configuration’ and test the integration end point using the curl command provided.

Setting up a Self-managed Gateway (APIcast)

Here is a summary of the steps involved in setting one up:

On 3scale:

  1. Login to 3scale
  2. click on the gear at the top right-hand corner of the screen and select Personal Settings then TokensClick Add Access Token and fill in the name for your token, check all checkboxes and select Read & Write for Permission.

    New Access Token
    New Access Token
  3. Click on Dashboard (near top right-hand corner) then APIs then shipping-products→Integration then edit integration settings, select APIcast Self-managed and click ‘Update Service’.

    Change To Self-Managed Gateway
    Change To Self-Managed Gateway
  4. Select edit APIcast configuration update staging and production public URLs to point to your self-managed gateway and click on ‘Update the Staging Environment’

    Set Self-Manage Gateway URLs
    Set Self-Manage Gateway URLs
  5. Click Integration and then promote v.X to production

On Openshift cluster:

  1. login as developer (assuming you are using ‘oc cluster up’ default user)
  2. create a project
    oc new-project 3scalegateway
  3. create a secret
    oc secret new-basicauth apicast-configuration-url-secret --password=https://ACCESS-TOKEN@ACCOUNT-admin.3scale.net

    Substitute ACCESS-TOKEN and ACCOUNT with your own

  4. Note that you can find documentation on Step 3 and 4 here.
  5. create an app
    oc new-app -f https://raw.githubusercontent.com/3scale/apicast/master/openshift/apicast-template.yml
  6. Log in to you Openshift Console
  7. Select Project 3scalegateway then Applications->routes and Create RoutesCreate the Staging and Production routes for the URLs you specified for staging and production public base URLs.Create Route

Using Swagger to Describe and Document My API

Swagger is now an open standard for documenting APIs (the OpenAPI Specifications or OAS) which is used by 3scale. Naturally, I want to use swagger to document my FIS ‘products’ service. I used the Online Swagger Editor to create my swagger file. The swagger editor is interactive meaning that when you change the yaml file on the left-hand pane, the changes are immediately reflected on the right-hand pane. This catches any error you made immediately. Everyone knows that to do things quickly, one should not start from scratch. This is exactly the reason why I used the petstore yaml file, which is the default file opened by the editor when you first access it, as my base document. I deleted the parts that I don’t need and customized the parts that I do want. The result is the yaml file attached downloaded using the editor’s File->Download YAML. However, 3scale requires a json file, this can easily be achieved using File-> Download JSON. The file contains descriptions on what the service does, its endpoint, the query parameters and the expected results. The 3scale Developer Portal uses the file content to create a document and renders the page based on it to allow developers to fill in the query parameters to try out the API.

swagger Files

Swagger Editor
Swagger Editor

Here are the steps to create the documentation and make it available in the Developer Portal.

    1. Login to 3scale
    2. Invoke APIs->Active Docs→Create a new specFill in the Name, System Name, paste in the JSON file created using Swagger Editor and click ‘Create Service’

      ActiveDocs
      ActiveDocs
    3. Select Developer Portal->New Page→New PageAdd name and path and json content shown below
      <h3>Active Docs/Swagger 2.0 Documentation</h3>
      {% active_docs version: "2.0" services: "products-docs" %}
      <script type="text/javascript">
      $(function () {
      window.swaggerUi.load();
      });
      </script>

       

      where “products-docs” is the ActiveDoc document we created in Step 2.

      1. Select Developers and then either create new group/Org. or use an existing oneI clicked on developer group and then User
        Users Of Developer
        Users Of Developer

        click on John Doe and then Edit when the page is displayed, change the password

        Change Password
        Change Password
      2. Select Developer Portal→Visit Developer Portallogin using John Do’s email address and password you just added

        Developer Portal Login
        Developer Portal Login
      3. Append the name of the new page to your URL for me, the URL after appending the page is: https://ayuen.3scale.net/shipping-products-docs fill in the query parameters and try out the service
      Product Page
      Product Page
      Try It Out
      Try It Out
      Try It Out Result
      Try It Out Result

       

      Here is a video that shows how to configure the cloud-based 3scale API Manager to expose the service described in https://youtu.be/c-Qvyuigfoo as an API. It also shows the Developer Portal which allows developers to look for APIs, their documentation and to try them out before incorporating them in their application. The documentation and ‘try it now!’ capability is provided by swagger specifications.

      Conclusion

      This concludes my first venture into the world of API Management. If you have followed the steps outlined in this article, you would have created and deployed your second API (usually first timers like myself create the Echo Service on 3scale as their first API) using a self-managed 3scale Gateway (APICast). You would also have learned how to create a swagger yaml file using the swagger editor. This has been just a dip of my toe in the water that is API Management. I shall document what I’ve learned after exploring other features of 3scale in future articles.