This topic explains the API Response Simulation button that appears in the upper-right corner of API Studio.

alt text

What is API response simulation?

When API Response Simulation is enabled (the slider button is green), all API responses generated by API studio are simulated. Simulation gives you a chance to play around with your API model and try out API calls without actually writing any “business logic” code.

So, while you are primarily focused on modeling your API, you can call your API paths using the Try this operation button in the generated doc, and API Studio returns a “mock” response. For example, the default Hello World project generates this simulated response:

{
  "message": "Sample text",
  "age": 1
}

As you can see, sample values are provided for each response object property. This response mimics a real response that would be generated when the API’s “business logic” is implemented in Node.js controllers.

The structure of the simulated responses is defined in the response definitions section of the Swagger file. See how the above simulated response corresponds to the HelloWorldResponse definition in the Swagger:

definitions:
  HelloWorldResponse:
    required:
      - message
    properties:
      message:
        type: string
      age:
        type: number

A real response from a fully implemented API might look like this:

{
   "message": "Hello, world!",
   "age": 21
 }

Disabling the simulator

You can only disable simulator by changing the default host and basepath elements in the Swagger to refer to a fully implemented API. How do you get a fully implemented API? Here are the basic steps:

  1. Download the API Studio project to a Node.js project. Select Download Node.js Project from the Project menu.

  2. Implement controller functions in Node.js for the API. How to write controllers is beyond the scope of this topic. But, basically, when you download your project, you receive, in effect, a project based on the npm swagger module. This module comes from the open-source project swagger-apis/swagger-node. You can refer to the swagger-node docs to learn all about swagger projects. The docs include a topic that walks you through how to write controllers.

  3. After you’re happy with your controller implementation, you can deploy your API project to a cloud-based Node.js platform.

  4. Once your API is deployed and available in the cloud, you can call it from API Studio by changing the basepath and host elements in the Swagger file to point to your deployment. This automatically disables the simulator, and if you call your API using the Try this operation button, it will return a response from your deployed API.

A weather API example

To wind up this topic, here’s a much larger example showing a sample response definition for a weather API, and then the simulated response. It’s got strings, numbers, arrays, and objects representing various aspects of weather data.

   WeatherResponse:
    properties: 
      base: 
        type: "string"
      clouds: 
        type: "object"
        properties: 
          all: 
            type: "number"
      cod: 
        type: "number"
      coord: 
        type: "object"
        properties: 
          lat: 
            type: "number"
          lon: 
            type: "number"
      dt: 
        type: "number"
      id: 
        type: "number"
      main: 
        type: "object"
        properties: 
          humidity: 
            type: "number"
          pressure: 
            type: "number"
          temp_max: 
            type: "number"
          temp_min: 
            type: "number"
          temp: 
            type: "number"
      name: 
        type: "string"
      sys: 
        type: "object"
        properties: 
          country: 
            type: "string"
          id: 
            type: "number"
          message: 
            type: "number"
          sunrise: 
            type: "number"
          sunset: 
            type: "number"
          type: 
            type: "number"
      weather: 
        type: "array"
        items: 
          type: "object"
          properties: 
            description: 
              type: "string"
            icon: 
              type: "string"
            id: 
              type: "number"
            main: 
              type: "string"
      wind: 
        type: "object"
        properties: 
          deg: 
            type: "number"
          speed: 
            type: "number"

If this were a fully implemented API, the weather response definition would return the following JSON in simulator mode. Objects, arrays, strings, and numbers are all “mocked up” with programmed values of the appropriate data type:

{
    "base": "Sample text",
    "clouds": {
        "all": 1
    },
    "cod": 1,
    "coord": {
        "lat": 1,
        "lon": 1
    },
    "dt": 1,
    "id": 1,
    "main": {
        "humidity": 1,
        "pressure": 1,
        "temp": 1,
        "temp_max": 1,
        "temp_min": 1
    },
    "name": "Sample text",
    "sys": {
        "country": "Sample text",
        "id": 1,
        "message": 1,
        "sunrise": 1,
        "sunset": 1,
        "type": 1
    },
    "weather": [
        {
            "description": "Sample text",
            "icon": "Sample text",
            "id": 1,
            "main": "Sample text"
        }
    ],
    "wind": {
        "deg": 1,
        "speed": 1
    }
}