

Deploying a REST API with a Mock Implementation¶

In addition to exposing an existing backend implementation as an API, Choreo Connect is also capable of responding to HTTP requests even without a backend. By changing the endpoint type to Mock Implementation, you can make Choreo Connect read the examples you have provided in the OpenAPI definition and respond to each HTTP request accordingly. While it supports default responses, you can also request specific responses using the HTTP headers Prefer and Accept.

Pick a method given below to start creating an API with a Mock Implementation.

Mode	Method
Choreo Connect with WSO2 API Manager as a Control Plane	Via WSO2 API Manager Publisher Portal
Choreo Connect as a Standalone Gateway	Via apictl for Standalone Mode

Updating the OpenAPI definition to generate a Mock Implementation¶

Abstract

With OpenAPI 3.0 you can provide the expected payloads and headers in the following formats.

Single Example for an Operation

Format

<resource path>:
  <operation>:
    responses:
      <response code>:
        description: <description>
        headers:
          <header>:
            example: <header example value>
        content:
          <media type>:
            example: <example>

Example

/pet/findByStatus:
  get:
    responses:
      '200':
        description: OK
        headers:
          x-wso2-example:
            example: example header value
        content:
          application/json:
            example:
              mock response: hello world

Multiple Examples for an Operation

Format

<resource path>:
  <operation>:
    responses:
      <response code>:
        description: <description>
        headers:
          <header>:
            example: <header example value>
        content:
          <media type>:
            examples: 
              <example reference>
                value: <example>

Example

/pet/findByStatus:
  get:
    responses:
      50X:
        description: Service Unavailable
        headers:
          x-wso2-example:
            example: example header value
        content:
          application/json:
            examples:
              ref1:
                value:
                  mock response: hello world
              ref2:
                value:
                  mock response: Welcome
      default:
        description: default response
        headers:
          x-wso2-example:
            example: default header value
        content:
          application/json:
            examples:
              ref1:
                value:
                  mock response: default hello world
              ref2:
                value:
                  mock response: default Welcome

Place Holder	Usage
`response code`	Can be 3 digit status code or a wildcard format like 2XX. `default` can be also provided instead of a particular status code.
`header`	Header name. You can provide multiple headers similarly under `headers`.
`media type`	Mock response content type. Provide allowed content types for the resource. When accept header is presented in a request, Choreo Connect will return the content which suited to accepted media type among them.
`example`	Provide the content body as a simple string or as an object. If an object is given as the `example`, it will be parsed to JSON format.

Note

For more information on defining response body examples in open API specification, follow Request and Response Body Examples.

Example

If you take the example in Multiple Examples for an Operation and update the API definition with it, you can use Prefer header and Accept header to get different examples for a resource if multiple examples were defined for the resource. Using Prefer header you can specify which code and/or example should be returned as the response for the mock request.

Invoking GET for /pet/findByStatus will return the default example as given below.

Request

curl -X GET https://localhost:9095/v3/1.0.6/pet/findByStatus

Response

< HTTP/1.1 200 OK
< content-type: application/json
< x-wso2-example: "default header value"
< 
{"mock response":"default hello world"}

Invoking GET for /pet/findByStatus with the header Prefer will return the matched example for the particular code and the example reference.

Request

curl -H 'Prefer: code=503, example=ref2' -X GET https://localhost:9095/v3/1.0.6/pet/findByStatus

Response

< HTTP/1.1 503 Service Unavailable
< content-type: application/json
< x-wso2-example: "example header value"
< 
{"mock response":"Welcome"}

Behavioral Characteristics

The following are the behavioral characteristics of the Mock Implementation with Choreo Connect.

Example not provided

If the invoked resource does not contain mock response examples provided in the api definition, then a response with 501, Not Implemented status code would be returned with 900871 error code.

Preferred Status Code in the Prefer Header

If the request has a valid integer value as the code preference, Choreo connect picks the most matched response examples from the OpenAPI specification checking on the exact codes and wild cards matches. Status code of the response will be same as the code preference given in the request. However, if there are no response examples matching the preferred status code, then 501, Not Implemented status code would be returned with 900871 error code.
If the request does not have a code preference, Choreo Connect will check for examples under default responses, if even no default responses are defined, then picks a one out of the response examples.

Accept Type in the Accept Header

If the request has accept-types, Choreo connect will pick examples defined under a matching media type. However, if there are no matches for accept types in the examples, then 501, Not Implemented status code would be returned with 900871 error code.
If the request does not have accept-types, Choreo connect will check for examples with 'application/json' as the media type. If there are no examples for 'application/json', then picks one out of available media-type examples.

Preference not found

If the request has an example preference, Choreo Connect will pick the example content with the matching example name from the example list we got after applying above steps. If there's no matching example found, then 501, Not Implemented status code would be returned with 900871 error code.

Via WSO2 API Manager Publisher Portal¶

Step 1 - Create a REST API¶

Start the WSO2 API Manager server with Choreo Connect as the Gateway.
Open API Publisher in the browser and create a REST API with the following values.

Field Value

Name SwaggerPetstore

Context /v3

Version 1.0.6

Endpoint Leave the endpoint field empty.

Step 2 - Implement the API¶

Step 2.1 - Update the OpenAPI Specification¶

Navigate to API Definition under API Configurations to view the OpenAPI specification.
Click edit to add mock examples to required resources.

Replace the default resources with the resource definitions given below.
Add response examples to OpenAPI Specification.

Update the OpenAPI definition referring to the examples given in Updating the OpenAPI definition to generate a Mock Implementation. You could also directly copy paste the sample for OpenAPI definition for Mock Implementation.
After adding examples to the OpenAPI specification, remember to click Update Content and Save.

Step 2.2 - Change the Endpoint Type¶

Navigate to Endpoints under API Configurations.
Select Mock Implementation as the endpoint type by clicking Add.
Select Choreo Connect as the gateway type.
Click proceed if a dialog box appears to disregard "mock endpoint implementation scripts".
View the mock examples that would be returned for each resource. If you need to modify the examples, you have to edit the API definition as mentioned before.
Click Save to enable mock implementation with OAS examples.

Step 3 - Deploy the API¶

Deploy the API from the Deployments tab from the left menu.

Step 4 - Invoke the API¶

Invoke the API the using the commands given in the Invoke the API section.

Via apictl for Standalone Mode¶

Initialize an API Project.

Use the following command to initialize an API. This is a sample OpenAPI definition containing example responses that will be referred by Choreo Connect to respond to API calls. Refer to Updating the OpenAPI definition to generate a Mock Implementation for more information.
```
apictl init petstore --oas https://raw.githubusercontent.com/wso2/product-microgateway/main/samples/openAPI-definitions/mock-impl-sample.yaml
```
Update the API Project.

Open the api.yaml file inside the API project and update endpointImplementationType to MOCKED_OAS.
```
endpointImplementationType: MOCKED_OAS
```
Deploy the API using the commands given in Deploy REST API - Standalone Mode
Invoke the API using the commands given below.

Invoke the API¶

After the APIs are exposed via Choreo Connect, you can invoke an API with a valid access token.

Let's use the following command to generate a JWT to access the API, and set it to the variable TOKEN.

TOKEN=$(curl -X POST "https://localhost:9095/testkey" -d "scope=read:pets" -H "Authorization: Basic YWRtaW46YWRtaW4=" -k -v)

Execute the following command to get different responses based on the examples you provided.

Default response for /pet/findByStatus

curl -X GET "https://localhost:9095/v3/1.0.6/pet/findByStatus" -H "Accept: application/json" -H "Authorization:Bearer $TOKEN" -k

Default response for /pet/findByTag

curl -X GET "https://localhost:9095/v3/1.0.6/pet/findByTag" -H "Accept: application/json" -H "Authorization:Bearer $TOKEN" -k

Example reference 1 for /pet/findByTag

curl -X GET "https://localhost:9095/v3/1.0.6/pet/findByTag" -H "Prefer: example=ref1" -H "Accept: application/json" -H "Authorization:Bearer $TOKEN" -k

Example for response codes 50X for /pet/findByTag

curl -v -X GET "https://localhost:9095/v3/1.0.6/pet/findByTag" -H "Prefer: code=503" -H "Accept: application/json" -H "Authorization:Bearer $TOKEN" -k

Example reference 1 of response codes 50X for /pet/findByTag

curl -v -X GET "https://localhost:9095/v3/1.0.6/pet/findByTag" -H "Prefer: code=503, example=ref1" -H "Accept: application/json" -H "Authorization:Bearer $TOKEN" -k

Field	Value
Name	SwaggerPetstore
Context	/v3
Version	1.0.6
Endpoint	Leave the endpoint field empty.

Deploying a REST API with a Mock Implementation¶

Updating the OpenAPI definition to generate a Mock Implementation¶

Via WSO2 API Manager Publisher Portal¶

Step 1 - Create a REST API¶

Step 2 - Implement the API¶

Step 2.1 - Update the OpenAPI Specification¶

Step 2.2 - Change the Endpoint Type¶

Step 3 - Deploy the API¶

Step 4 - Invoke the API¶

Via apictl for Standalone Mode¶

Invoke the API¶

See Also¶