How to migrate OpenWhisk api-experimental APIs

Share this post:

Deprecation of “wsk api-experimental” Command

Earlier this year, the wsk api command was introduced as the replacement for the wsk api-experimental command.

The wsk api-experimental command is now deprecated and will be withdrawn at the end of July, 2017.  On August 1st, all APIs created with the wsk api-experimental command will be removed.

Migrating APIs

You must manually migrate any APIs created with the wsk api-experimental command if you want to continue using and managing them with the wsk api command.

Differences between wsk api-experimental and wsk api

Before migrating APIs created with the wsk api-experimental command, here is what you need to know: APIs created with the wsk api command now have greater control over HTTP requests and responses. So, when migrating an API created with wsk api-experimental, you should expect the wsk api command to operate on the migrated APIs with the new level of control.

wsk api-experimental

wsk api


OpenWhisk action used to create the API


Standard OpenWhisk action. JSON input and JSON output.


OpenWhisk web-action only.  Input and output is not restricted to just JSON.


Access to HTTP request details




Yes.  The HTTP request method, request headers, query parameters and body are accessible.


Control over HTTP response


Partial. Control the JSON content in the body.


Yes.  Control the response headers, status code and response body.


Read more about OpenWhisk web actions here.  To manage APIs from the OpenWhisk Dashboard, click the APIs tab.

Migration Procedure

  • Determine if the api-experimental API uses an action that returns errors via exceptions or rejected promises
  • If the action does not return errors via exceptions or rejected promises, follow the simple migration steps
  • If the action does return errors via exceptions or rejected promises, follow the advanced migration steps

Simple Migration

If the API action does not return errors via exceptions or rejected promises, migration is easy.

Step 1

Using the same action code, create a new OpenWhisk action; but this time create the action as a web action using the web true flag:

wsk action create MyWebAction myaction.js web true

Step 2

Then create your new API using the new web action:

wsk api create /BASEPATH /PATH VERB  MyWebAction

That’s it!  Validate your new API’s behavior by invoking the resultant URL with your preferred RESTful tooling, such as curl.

Advanced Migration

If an API uses an action that returns errors via exceptions or rejected promises, you will have to make code changes to generate the same 502 error response status code and error body format.  In fact, you can respond with any status code–not just 502–that accurately reflects your action’s error response.

Step 1

For the action to control the status code value, you must create the API to invoke the web action with the .http content extension. Actions invoked with the .http extension have the responsibility and flexibility of providing the HTTP headers, status code, and body. Both successful responses and error response must be converted.

Let’s look at an error response example.

We assume the api-experimental action’s error response looks something like:

function main(message) {

return Promise.reject(“My error message”);


When this API is called, it will return a status code of 502 along with the following results:


“error”: “My error message”


If this same action code were used unchanged to generate the web action and associated API, the resultant response will have a status code of 400 (Bad Request) with the following response body, where the code value is an internal integer value that can be ignored:


“error”: “Response is not valid ‘application/json’.”,

“code”: 73974


To generate the correct response, update the action code to pass the desired status code of 502, the body type of application/json, and the JSON body (which is treated as a binary payload and so must be base64 encoded):

function main(params) {

bodyobj = {‘error’: ‘My error message’};

return Promise.reject({

statusCode: 502,

headers: { ‘Content-Type’: ‘application/json’ },

body: new Buffer(JSON.stringify(bodyobj)).toString(‘base64’)}



Note that the response contents are wrapped inside a JSON object having “error” as the only field. This is needed to mimic the exact experimental api error response body.  If this format is not important, then the “error” field is not necessary; however, the body must be a JSON object and not just a JSON string.

Step 2

Now create the web action

wsk action create MyWebAction myaction.js web true

Step 3

Create the new API using the wsk api create command with the http response type:

wsk api create /BASEPATH /PATH VERB MyWebAction response-type http


The new API’s response matches the original wsk api-experimental command’s response.  Both return a status code of 502 along with the following response body:


“error”: “My error message”


Step 4

Repeat steps 1-3 as needed.

Construct all error responses–even exceptions thrown by modules outside of your immediate code–to be returned in the same way demonstrated in the example.

Construct all successful responses in the same way, except by using a statusCode value of 200 instead.



Bluemix OpenWhisk Development

More How-tos stories
May 3, 2019

Kubernetes Tutorials: 5 Ways to Get You Building Fast

Ready to start working with Kubernetes? Want to build your Kubernetes skills? The five tutorials in this post will teach you everything you need to know about how to manage your containerized apps with Kubernetes.

Continue reading

May 3, 2019

Using Portworx to Deploy and Manage an HA MySQL Cluster on IBM Cloud Kubernetes Service

This tutorial is a walkthrough of the steps involved in deploying and managing a highly available MySQL cluster on IBM Cloud Kubernetes Service.

Continue reading

May 2, 2019

Kubernetes v1.14.1 Now Available in IBM Cloud Kubernetes Service

We are excited to announce the availability of Kubernetes v1.14.1 for your clusters that are running in IBM Cloud Kubernetes Service. IBM Cloud Kubernetes Service continues to be the first public managed Kubernetes service to support the latest upstream versions from the community.

Continue reading