Prototyping APIs in WSO2 API Manager with Mock Response Payload Generation

This article is an informative step by step introduction and guide on how to prototype APIs in WSO2 API Manager with the help of mock response payload generation for writing inline scripts.

What is API Prototyping?

This is the process through which an API publisher can deploy a mock up version that can be used to test a concept and allow consumers to test, try out and provide feedback in order to make requested changes and improvements to APIs. This allows publishers to gain as many practical insights as possible while saving up on resources such as time and effort.

How does a prototype API work?

A prototype API behaves similar to the original API but lacks functional and non-functional properties of the original component and returns static data rather than fetching it from a database or a dynamic data source.

Therefore, a prototype API is an impersonation of a real API that returns pre-defined responses, response codes, headers, parameters, etc.

What are the benefits of prototyping APIs?

• Testing — consumers can test out APIs and provide feedback regarding changes to be made/requested or bugs. This allows for quick testing and bug fixing.
• Practical Insights — critical implementation and usability issues can be addressed with minimal effort.
• Lower barrier for developers — Front-end developers can ensure they are working with an API that will satisfy them by creating endpoints they wish to see and provide corresponding endpoint status codes, response bodies and headers. Back-end developers have the ability to iterate on the API design till they are satisfied with how it looks, they can leave the complex logic until they know how it is supposed to work.
• DevOps — Reduces amount of dependencies thus supporting DevOps.

How does WSO2 API Manager support API Prototyping?

The 3.1.0 release of WSO2 API Manager has quite effectively enhanced the support for prototyping API. New APIs or new versions of existing APIs can be deployed as prototypes, allowing subscribers to test APIs without subscriptions or monetisations. This gives API publishers a larger audience and a greater scope for improving APIs.

Previous Scenario:

Users would be presented with an inline script which had to be edited manually for each resource. The default script requires the user to edit it from scratch in order return a response in the developer portal.

New Scenario (with API Manager version 3.1+):

Prototype implementation is now equipped with Mock Response Payload Generation which works for OAS 2.0 (fka Swagger) and OAS 3.0.

Users can prototype an API using the built-in JavaScript engine without writing the JavaScript implementation for each resource manually. The inline scripts will be generated automatically for each response code and payload type (JSON and / or XML) according to the response body example values or response schemas defined in the API Definition/Swagger.

If the API definition contains mock responses for more than one response code per-resource, the payloads will be presented as multiple payloads but the “mc.setPayloadJson or mc.setPayloadXML” will only contain the lowest response code value. Furthermore, inline scripts of each resource can be further modified by users to suit the required outcome.

Once the generated mock payload scripts have been saved, the API can be deployed as a prototype and be tested in the developer portal.

How to Prototype an API with WSO2 API Manager ?

Now, let’s get down to business and go through the steps of how to create a Prototype API in WSO2 API Manager.

Step 1 — Defining Sample/Mock Response Payloads in Swagger

There are multiple ways in which sample response examples can be defined in Swagger (OAS 2.0) and OAS 3.0. To learn more on how to do so, follow the Swagger documentation on “Adding examples”.

Adding Examples

Adding Examples

Let’s use the Swagger Petstore example for the following steps.

https://petstore.swagger.io/v2/swagger.json

Step 2 — Generating and Modifying Inline Scripts

1. Click CREATE NEW API, and click I Have an Existing REST API.

2. Upload the OpenAPI URL or OpenAPI File and click NEXT.

3. Provide the API name, context, and version. Since we are creating a prototyped API, make sure the endpoint field is empty. Thereafter, click CREATE.

You are then directed to the API overview page.

4. Click Endpoints to navigate to the Endpoints page.

5. Select Prototype Implementation as the endpoint type, and click ADD.

The Endpoints page appears.

6. Click and expand any of the methods that contain a sample/mock payload to view the inline script that has been generated.

var response200json = [ {
  "id" : 0,
  "category" : {
    "id" : 0,
    "name" : "string"
  },
  "name" : "string",
  "photoUrls" : [ "string" ],
  "tags" : [ {
    "id" : 0,
    "name" : "string"
  } ],
  "status" : "available"
} ]
mc.setProperty('CONTENT_TYPE', 'application/json');  
mc.setPayloadJSON(response200json);                 

The example response defined in the OpenAPI definition is set as the mock response payload. You can modify the generated inline scripts as required.

7. Modify the inline script for /pet/{petId}.

Let’s modify the generated inline script to suit our requirement, which is to allow the user to enter an ID of a pet and get a response corresponding to the entered ID.

// **GENERATED CODE** //
var response200json = [ {       
  "id" : 0,
  "category" : {
    "id" : 0,
    "name" : "string"
  },
  "name" : "string",
  "photoUrls" : [ "string" ],
  "tags" : [ {
    "id" : 0,
    "name" : "string"
  } ],
  "status" : "available"
} ]
// **MANUALLY ADDED CODE** //
if (mc.getProperty('uri.var.petId') == 1) {         
  response200json = {
    "id" : 1,
    "category" : {
      "id" : 1,
      "name" : "Dog"
    },
    "name" : "doggie",
    "photoUrls" : [ "string" ],
    "tags" : [ {
      "id" : 1,
      "name" : "German Shepherd"
    } ],
    "status" : "available"
  }
}
mc.setProperty('CONTENT_TYPE', 'application/json');
mc.setPayloadJSON(response200json);

8. Click SAVE to save the API.

Now that we’ve completed generating and modifying inline scripts, it’s time to deploy our prototype.

Step 3 — Deploy the API as a Prototype

1. Click Lifecycle to navigate to the Lifecycle page.
2. Click DEPLOY AS A PROTOTYPE to deploy the API as a prototype.

After deploying the prototype, we can invoke the API and test it using the Developer Portal.

Step 4— Invoke the API

1. Click View in Dev Portal to navigate to the Developer Portal after the API is deployed.
2. Click Try Out to navigate to the API Console.

3. Expand any method and click Try it out.

Enter the value for the parameter and click Execute to invoke the API.

Note that the payload that you gave as a JSON/XML output appears in the response for each respective parameter provided.

i). For petId : " 0 " :

The response payload that is defined in the generated script is returned.

ii). For petId : " 1 " :

The response payload defined in the manually modified script is returned.

We successfully created an API with an inline script, deployed it as a prototype, and invoked it via the integrated API Console.

An API can also be prototyped by moving the API to the PROTOTYPED state by changing the API lifecycle state and providing the prototype endpoints.

Once the API prototype has been tested thoroughly, the final version of the prototyped API is can be released in the publisher.

Conclusion

As the number of businesses and organisations progress towards APIs, the Mock Payload Generation Feature has made the lives of developers much easier, by providing a DevOps friendly requirement with an efficient and effective way for prototyping APIs.

Learn more…

About WSO2 API Manager :

https://wso2.com/api-management/

Official WSO2 Screen Cast of this feature :

https://www.youtube.com/watch?v=Hn2eR_h4cf0&t=266s

Official WSO2 Documentation for this feature :

https://apim.docs.wso2.com/en/latest/learn/design-api/mock-api/create-a-mock-api-with-an-inline-script/#creating-a-prototype-api-with-mock-payload-generated-inline-scripts