IBM Developer Blog

Follow the latest happenings with IBM Developer and stay in the know.

Learn more about OpenAPI Specification, an exciting new way to define your APIs.


Please note that you will need version 1.0.39 (or higher) of the cloud-functions/wsk/functions/fn plugin to test this out.

Powered by the Apache OpenWhisk project, IBM Cloud Functions is a serverless, event-driven programming platform designed for developing snippets of code set to perform a specific task. IBM Cloud Function’s ibmcloud fn deploy is a tool for capturing the configuration of a larger IBM Cloud Functions deployment, such as defining a state for all deployed actions, APIs, triggers, rules, and more.

My colleagues and I have been working hard over the last few months to deliver a new way of defining APIs in OpenAPI Specification format to Apache OpenWhisk, and I am excited to announce it is now available in IBM Cloud Functions!

This new feature comes with several advantages, including:

  1. It is the state returned from IBM Cloud Functions when using ibmcloud fn api get $API_NAME, so you are able to effortlessly capture existing manual API deployments for reproducibility, version control, and more.

  2. There is a thriving ecosystem of tools around OpenAPI Specification for doing everything from stub code generation to automated documentation.

Use OpenAPI Specification with ibmcloud fn deploy

OpenAPI Specification is easy to use with ibmcloud fn deploy manifest files. To use the OpenAPI Specification, you need to give a path to the specification to the keyword config under project. Let’s walk through a quick example.

Below is the manifest.yaml:

project:
  config: open_api_spec.json
  packages:
    hello_world_package:
      version: 1.0
      license: Apache-2.0
      actions:
        hello_world:
          function: src/hello.js
          web-export: true

Below is an example OpenAPI Specification. Note that your OpenAPI Specification will be unique to your account/namespace.

{
    "swagger": "2.0",
    "info": {
        "version": "1.0",
        "title": "Hello World API"
    },
    "basePath": "/hello",
    "schemes": [
        "https"
    ],
    "consumes": [
        "application/json"
    ],
    "produces": [
        "application/json"
    ],
    "paths": {
        "/world": {
            "get": {
                "description": "Returns a greeting to the user!",
                "operationId": "hello_world",
                "responses": {
                    "200": {
                        "description": "Returns the greeting.",
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        }

    },
    "x-ibm-configuration": {
    "assembly": {
      "execute": [
        {
          "operation-switch": {
            "case": [
              {
                "operations": [
                  "getHello"
                   ],
                "execute": [
                  {
                    "invoke": {
                      "target-url": "https://openwhisk.ng.bluemix.net/api/some/action/path.http",
                      "verb": "keep"
                    }
                  }
                ]
              }
            ],
            "otherwise": []
          }
        }
      ]
    }
  }
}

There are several elements to discuss:

  1. Under the project.config in the manifest, specification of where the location of the OpenAPI Specification file takes place.

  2. basepath defines the base of the API being defined. So, in this example, all of our API endpoints will be prefaced with /hello.

  3. paths map an API endpoints to the web action processing the request. Using the example above, the path /world receives a request and subsequently invokes the hello_world web action to process the data from the request and return a response to the caller. The endpoint for this API action is located at $YOUR_URL/hello/world, where $YOUR_URL is the URL for your API.

  4. x-ibm-configuration sets up the API Gateway with the necessary values, including the target URL of the action. Note that this can also be used to set up whether cross origin resource sharing can be enabled.

  5. There are more features, including client IDs, clients secrets, and rate limiting. For IBM Cloud, you must use the x-ibm-rate-limit key instead of x-gateway-rate-limit which is used in the open source documentation.

For more information, see the reference documentation.

How to use OpenAPI Specification with existing APIs in IBM Cloud Functions

If you have an existing API, you can start using this feature immediately by getting the existing OpenAPI Specification stored by the API Gateway. To do this, use the ibmcloud fn tool and write the output to a file. For example, an API named “foobar”, defined without an OpenAPI Specification file, can get an OpenAPI Specification through:

ibmcloud fn api get foobar > foobar_openapi_spec.json

You can then add a key/value pair, such as project.config, to point to foobar_openapi_spec.json in the manifest. When both an OpenAPI Specification and a manifest defined API are present, the OpenAPI Specification API takes precedence.

Summary

OpenAPI Specification is an exciting new way of defining your APIs in a format with a rich ecosystem. Don’t forget to check out the Apache OpenWhisk project and sign up for a free IBM Cloud lite account to begin your journey today! Thank you for reading and happy hacking!