How to migrate OpenWhisk api-experimental APIs

By: Mark Deuser

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.


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 migrationsteps

  • 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.

Be the first to hear about news, product updates, and innovation from IBM Cloud