APIs

Let's now show how these web actions can be turned into an API using the API Gateway. First we will choose /myapi as the base path. This is the part of the path before the actual endpoint. For example: example.com/basepath/endpoint. This is useful for grouping endpoints together in a logical way and is how IBM Cloud Functions organizes your endpoints into a single API.

Creating an API

Hello Endpoint

First we will create the hello endpoint. Note that all actions used in an API must be web actions, so we mustn't forget to run ibmcloud fn action update hello --web true prior to following commands below.

1. Run the following command to create a simple GET endpoint for the hello action

    ibmcloud fn api create myapi /foo get hello

2. Check to see the API was created

    ibmcloud fn api list

    ok: APIs
    Action                                     Verb  API Name  URL
    /NAMESPACE/hello        get    myapi  https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/d9903f40439f1a268b7dcbac42a389cdde605f3f3bef57f69789be6df438361e/myapi/hello

3. Now lets invoke that API via curl

    curl https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/aac6bc4a6f94f19dd008e64513b62bf155af5703a95a142f0c9a6ea83af81300/myapi/foo

    {
    "greeting": "Hello, undefined from Rivendell"
    }

4. Create the endpoint for the atom svg action

    ibmcloud fn api create myapi /atom get atom --response-type http

    ok: created API /myapi/atom GET for action /_/atom
    https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/NAMESPACE_ID/myapi/atom

5. Test out the action by copy/pasting the endpoint into your browser of choice.

   What do you see?

All HTTP Methods are supported... GET, POST, PUT, or DELETE. For details see: Serverless HTTP handlers with OpenWhisk

Using OpenAPI Specification ("Swagger")

As we can begin to tell, as the number of API endpoints increases, documenting and managing them becomes increasingly difficult. One solution to this to use the OpenAPI Specification. This has a plethora of tools around for documenting, creating stub projects, etc in a variety of languages. And it is supported by IBM Cloud Functions!

You may create all your APIs with a single OpenAPI JSON documents on the create command...