Create Serverless Cloud Functions with Managed REST APIs and API Keys
Cloud Functions are maturing very very fast! It takes no more than 15 minutes to create a fully auto-scalable and securely managed API endpoint to access a single or a sequence of Cloud Functions that are access restricted by a professional developer portal with API key management. That’s a pretty powerful feat for any developer.
The goal here is to create a single REST API endpoint ‘POST /chat’ and a sequence REST API endpoint that triggers Push Notifications of received requests to a WebSocket connection at ‘ws://hostname/ws’. The WebSocket endpoint logs received notifications into a MongoDB database. Finally, I want to secure access to my APIs by API keys with an API manager, in this case API Connect.
To set this up I execute the following steps in Cloud Functions:
- Create an Action ‘chat’,
- Create a Sequence ‘ChatPush’,
- Create Managed API with Developer Portal,
- Test the API.
But first, I created a Node.js server using Node-RED without Cloud Functions that implements the following flows:
To install and setup the above flow in Node-RED follow these instructions:
- Install Node-RED and open the visual editor,
- Open the menu, open the ‘Palette manager’, click the ‘Install’ tab,
- Search for ‘mongodb2’, find ‘node-red-contrib-mongodb2' and click the ‘install’ button,
- Go to the Node-RED Flow library, and search the flow with title ‘Log Push Notifications with WebSockets to MongoDB’,
- Follow the import instructions.
- Point your MongoDB node to a MongoDB instance, e.g. CosmosDB on Azure or MongoDB Atlas.
In this article however, I am recreating the part that executes the ‘Push Notification Server’ workflow, but this time as a Cloud Function with an API Manager to control access to the endpoints using API keys.
Create an Action ‘chat’
Go to Bluemix.net and login to your account. Signup if you don’t have an account yet. For students and academic staff, you can get an academic promotion code at onthehub.com/ibm.
In the ‘Bluemix Dashboard’, from the top-left menu, click the ‘Functions’ item.
In the ‘Overview’ page of the ‘Functions’ dashboard, in the left menu, click the ‘Develop’ item.
This brings you to the Cloud Functions developer IDE.
Click the ‘Create an Action’ button.
For ‘Choose a name for your action’ enter ‘chat’, under ‘Choose an Execution Runtime’ select ‘Node.js’, under ‘Select a sample (or blank) to start with’ choose the ‘Hello World in JavaScript’, and click the ‘Create Action’ button.
Change ‘message’ to ‘msg’ as ‘message’ is a reserved word that will cause problems later in the setup. Click the ‘Make It Live’ button to deploy your changed Cloud Function.
2. Create a Sequence ‘ChatPush’
Next, I create a Sequence if Functions and use the
Click the ‘Link into a Sequence’ button at the bottom of the ‘chat’ function editor. In the ‘Configure a New Action Sequence’ window, you see a list of existing packages. Scroll down and click the ‘WEBSOCKET’ package.
Click the green ‘NEW BINDING’ hexagon.
Name the new binding or package ‘ChatPushPackage’, and in the ‘uri’ input control enter the WebSocket connection string, e.g. ‘ws://remkohdev-nodered.mybluemix.net/ws’ to which the sequence should connect to send Push Notifications.
Click the ‘Save Configuration’ button.
Click the ‘Add to Sequence’ button. Review the draft of the new Sequence.
And click the ‘This Looks Good’ button. Name the new Sequence ‘ChatPushSequence’, click ‘Save Action Sequence’, and click ‘Done’.
We need to make an important change to the ‘chat’ action now! Edit the ‘chat’ action, and change the return message by replace the ‘msg’ node by a ‘payload’ node, in the response message. This is necessary, because the WebSocket package in the sequence expects a ‘payload’ node to pass the input.
function main(params) {
return { "payload": "you sent me " + params.msg };
}Click the ‘Make It Live’ button to deploy the changes in the ‘chat’ action.
At the bottom of your ‘chat’ action, click the ‘View REST Endpoint’.
Click the ‘Show Full Command’ link. Copy the expanded full cUrl command, including the Authorization string, to test your API.
$ curl -d '{ "msg": "yo smo says hello" }' 'https://openwhisk.ng.bluemix.net/api/v1/namespaces/remkohdev%40us.ibm.com_dev/actions/chat?blocking=true' -XPOST -H 'Content-Type: application/json' -H 'Authorization: Basic NWU4YTAweirdStringGHJKWTYU1='
{"duration":53,"name":"chat","subject":"remkohdev@us.ibm.com","activationId":"6e8e195f597449f18e195f597409f176","publish":false,"annotations":[{"key":"limits","value":{"timeout":60000,"memory":256,"logs":10}},{"key":"path","value":"remkohdev@us.ibm.com_dev/chat"}],"version":"0.0.5","response":{"result":{"payload":"you sent me yo smo says hello"},"success":true,"status":"success"},"end":1507607609732,"logs":[],"start":1507607609679,"namespace":"remkohdev@us.ibm.com_dev"}Close the ‘View REST Endpoint’ window. Click the ‘Monitor’ item in the left menu, and review the ‘Activity Log’ to check your Function is running.
Under ‘MY SEQUENCES’ click the ‘ChatPushSequence’ sequence, and click the ‘Run this Sequence’ to test the sequence set up. Enter a JSON string under the ‘JSON Input’.
{
"msg": "Testrun this Sequency Yo 1"
}Click the ‘Run with this Value’ button. You should see your test run finish with a green bar to indicate it ran successfully.
Click the ‘Close’ button in the bottom right, and in the top right click the ‘View Sequence Details’.
Under ‘Web Action’ check the ‘Enable as Web Action’ checkbox. Copy the ‘Web Action URL’ and append the URL parameter ‘msg’.
https://openwhisk.ng.bluemix.net/api/v1/web/remkohdev%40us.ibm.com_dev/default/ChatPushSequence.json?msg=wohoo_pohooRun the full Web Action URL in your web browser.
Back in the Cloud Functions manager, in the left menu, under the ‘Triggers’ item you can connect this action sequence with Triggers in Cloud Functions.
3. Create Managed API with Developer Portal
Click ‘Manage’ in the breadcrumb, click the ‘APIs’ item in the left menu, and click the ‘Create an OpenWhisk API’ button.
In the ‘Create API for Cloud Functions’ window, in the ‘API Info’ window, under ‘API name’ enter ‘ChatPushAPI’, and under ‘Base path for API’ enter ‘/api’.
Click the ‘Create operation’ button.
Under ‘Path’ enter ‘/chat’, select ‘POST’ under ‘verb’, and under ‘Action’ make sure the ‘chat’ action is selected. Click the ‘Save’ button.
You created a REST API endpoint for JUST the ‘chat’ action. Create a second operation that calls the sequence now!
Click the ‘Create operation’ button.
Under ‘Path’ enter ‘/chatpush’, select ‘POST’ under ‘verb’, and under ‘Action’ make sure the ‘ChatPushSequence’ action is selected. Click the ‘Save’ button.
In the ‘Security and Rate Limiting’ window, switch on the toggle for ‘Require applications to authenticate via API key’.
Optionally, you can decide the limit the rate by switching on the toggle for ‘Limit API call rate on a per-key basis’. For the purpose of this article I am not switching it on, but you could.
Scroll down and click the ‘Save’ button.
In the left menu, click the ‘Sharing’ item.
Make sure that the ‘Expose Managed API’ toggle is active. In the ‘Sharing Outside of Bluemix Organization’ window, click the ‘Create API key’ button. Enter a ‘Descriptive name’ for the API key, e.g. ‘ChatPushPublicAPIKey’ and click the ‘Create’ button. Refresh or reload the page if you don’t see the API key immediately.
4. Test the API
Creating the API key, also created an ‘API Portal Link’. Click the ‘API PORTAL LINK’ to go to the Developer Portal.
First, select the postChatpush Operation in the left menu, then click the ‘Try it’ link for the corresponding operation. Each operation you create for the API will have a ‘Try it’ button in the portal, which is supported by the Open API Initiative.
Copy-paste the API key into the ‘X-IBM-Client-ID’ HTTP header under Identification,under ‘Parameters’ in the ‘body’ window enter a JSON message.
{ "msg":"saying hi from the dev portal" }and click the ‘Call operation’ button. You should get a Response code: 200 with a Response body.
{ "msg": "you sent me saying hi from the dev portal" }Now, test the ‘chat’ operation, and note that the sequence is not triggered this time.
Congratulations, you released an API key managed API into production with a fully scalable Cloud Function ready for the year 2018.
