Documentation

Overview

The goal of this documentation is to introduce you to the terms and JSONs you’ll see in Mockswitch. This page will quickly introduces the core concepts involved. The remaining pages will dive a bit deeper into each one. After everything is explained, we’ll discuss ways you can integrate your system with ours.

Installation

Desktop app

Note: Mockswitch requires user signing up before going through concepts.

If you have not already signed up to mockswitch, please sign up before continuingopen in new window.

Installation of the App comes in two flavours

Next, download the app

  1. Visit mockswitch.com/downloadsopen in new window.
  2. Click Download.
  3. Once the download is complete, open a Finder window and select your Downloads folder.
  4. Double click the Mockswitch .dmg file. This will open a small window.
  5. Drag and drop the Mockswitch icon to the Applications folder in the window.
  6. To launch the Mockswitch app, open the Applications folder and double-click the Slack icon.

Command Line

Workspaces

Getting started

  • Sign up for a Mockswitch Accountopen in new window. If you want to create a Workspace for your team, we recommend signing up with an email address that’s associated to your company.
  • When you signup the very first time, you are already part of workspace that is named by you. If you choose to upgrade the workspace click on Upgrade workspace else choose Create new workspace and follow the next steps.
  • A user can be part of multiple workspaces for example be a owner of one while a member at another.

Create Workspace

Settings

Storage

Before we begin creating services we should take a look at what and where the meta data of a service resides. Mockswitch doesn"t store any project data which gives you full control over your data. Settings module gives you different ways you could configure each aspect of the app. You can easily switch between different connectors based on your needs, services will reregister automatically after switch.

Local drive

Use this connector for local development, this mode doesnt support collaboration but useful for rapid prototyping.

Choosing Local drive

Github

You must have Git installed before using Mockswitch. If you do not already have Git installed, you can download and install the latest version of Git from https://git-scm.com/downloadsopen in new window.

After you have Git installed, you"ll need to configure Git for Mockswitch App.

Configuring git for Mockswitch

Mockswitch uses Git as the primary storage of service metadata information and the Git could be a private repo or any url is known to you and your team. You could have different instances of Mockswitch pointing to different Git URLs. Each repo could connect to N number of branches. It all depends on your needs. You could use different branches for different environments for example.

Choosing Local drive

Mongo

Another fast and great connector is using MongoDB. Configuring mongo is easy and simple.

Choosing Local drive

Mock server

Host and port to which all services are mapped, this can be changed anytime to suit your needs.

Mock server

User settings

User settings are personal preferences which are stored per user.

Environment variables

Environment variables are useful when we want to use dynamic replaceable keys instead of static values. You can use :key in your URLs, headers, queries to replace it with its value defined here or pass the value using request headers to override the environment variable defined here per request basis.

Environment Variables

Services

Mock services are listed based on grouping. Grouping can be done manually using service group field in each of the services. If a grouping is not mentioned Mockswitch will assign a default / smart grouping of services.

Mock services listing

Create a service

You can create a service using clone of an existing example services and modifying it. Its the preferred way though you can also start by creating a new service using "New Service" button.

Clone a service

Clone a service

Update a service

By default user lands in editable mode for service body to easily update the response while for some uncommon scenarios such as updating a service header information there is a pencil icon to edit it.

Update a service endpoint

Update the method, endpoint, add a delay or toggle service active status. Services are unique based on endpoint URL and method.

Update a service endpoint

Delete a service

Clicking on trash icon deletes a service.

Tip

Alternatively, service can be deactivated by toggling the active status.

Deleting a service

Test a service

You can start testing by clicking on the arrow next to endpoint link.

Test mock service

Mockswitch has a fully integrated service tester which is used to not only test mock services but also any external services. We currently only support REST api calls.

Service tester

Switch case responses

Response are defined as switch case control. Each response case is associated with a rule and if the request matches the rule, it triggers the response associated with response case.

Case matching

Switch case

Configuring cases

By default user lands in the default case of service details. To add new response cases to the service click on plus icon as shown below.

Response case

A new response case will show up below.

Response case 1

Next, configure response for case.

Response

Configure response type for response case / default response. For detail usage for different response types see below.

Response case 1

Body

Define the response JSON and status.

Response body

Post processing

Post processing can be done on top of the response type if there is a need for any dynamic replacement of values. For example if there is a need to replace productId passed in request with response body. This can be done using merge type of post processing. The merge type will first generate the sample JSON based on request properties and then merge the content with response from previous step.

The Replace function will replace the dynamically generated JSON based on post processing template and replace the content without merging - this is helpful is defining your dynamic pre configured JSON.

Mockswitch transform is a simple, yet powerful way of transforming JSON from one format to another.

The use case for which it"s designed is where you"re doing repetitive processing that involves instances of a particular JSON document format being converted into some other JSON format.

It takes an instance of request JSON, and transforms it to a new output JSON response, using rules defined in a template JSON.

For example, the response output might look like this:

      {
        product: {
          productId: "hello",
          productcode0: "world" 
        }
      }
1
2
3
4
5
6

The important feature of the template JSON is that it defines the structure of the new output JSON, as well as defining the value of each of its leaf nodes in terms of the response output document"s property paths.

Each element within the response output that is to be used as the value for an output JSON element is specified within the template as a quoted string, within which the value is inside double curly braces. For example:

      var templateObj = {
        color: "{{request.body.productId}}",
        size: {
          weight: "{{request.body.productName}}",
          d: "literal text",
          e: "hello {{request.body.productName}} again"
        }
      };
1
2
3
4
5
6
7
8

Note the d property in the template above is defined as literal text without any curly braces, so the literal text value will be used in the output JSON as a fixed value.

Note also the e property in the template, showing how an input path reference can be embedded inside other literal text.

The output would be:

      {
        "color": "black",
        "productId": {
          "weight": "2 pounds"
        }
      }
1
2
3
4
5
6

You can also specify that the output JSON is to contain an array which is mapped from some array within the response output. For example, suppose the response output is:

     {
        product: {
          productId: "TY6773",
          productcode0: "TI6773" 
        },
        arr: [
          {
            code: "T3562",
            code0: "U8930"
          },
          {
            code: "T4933",
            code0: "U8932"
          },
        ] 
      }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

We could map the names into an array within the output JSON by defining an array mapping rule in the template. For example, see the people property in the template JSON below:

      {
        color: "{{request.body.productId}}",
        size: {
          weight: "{{request.body.productName}}"
        },
        people: [
          "{{request.body.arr}}",
          {
            firstcode0: "{{request.body.name}}"
          }
        ]
      };
1
2
3
4
5
6
7
8
9
10
11
12

people is defined as an array, containing two elements:

  • the first element defines the array property to use within the response output. In our case we want to use input.arr, so we just specify JSON .

  • the second element, if present, specifies the template JSON to create as each element of the output array.
    Note that the response output properties you specify in the mappings are relative to the input JSON"s parent array that you specified in the first element above. So, in the example above, they are relative to the response output"s array. Hence, for the output JSON"s firstName property, you merely specify , which tells the transformer to use the name property from each array element within the response output"s * array.

    The template array JSON can be as simple or as complex as you like, and can define lower-level arrays and/or JSONs if required.

  • if the second element isn"t defined, the array specified in the first element is copied directly into the output property.

The output JSON created from the example above would now look like this:

      {
        "color": "white",
        "productId": {
          "weight": "2 pounds"
        },
        "users": [
          {
            "firstName": "John"
          },
          {
            "firstName": "Doe"
          }
        ]
      }
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Here"s a more complex example:

  // response output:
    {
        product: {
          productId: "PRD001",
          productcode0: "PRD002" 
        },
        level2: {
          arr: [
            {
              firstName: "John",
              hobbies: ["movies", "hifi"]
            },
            {
              firstName: "Doe",
              hobbies: ["movies hiking"]
            },
          ]
        } 
      }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
  //  Post processing template
     {
        color: "{{request.headers["x-test-color"]}}",
        size: {
          weight: "{{environmentVariables.ENV1}}"
        },
        people: [
          "{{request.body.arr}}",
          {
            firstName: "{{request.body.name}}",
            hobbies: [
              "{{request.body.hobbies}}"
            ]
          }
        ]
      }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

The output JSON created from this transformation would be:

      {
        "color": "orange",
        "productId": {
          "weight": "2 pounds"
        },
        "users": [
          {
            "firstName": "John",
            "hobbies": [
              "movies",
              "hiking"
            ]
          },
          {
            "firstName": "Doe",
            "hobbies": [
              "movies hiking"
            ]
          }
        ]
      }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Response types

Basic response

Mockswitch's plain jay response type. Set with JSON body and you are all set.

Tip

Make the plain response dynamic by using post processing transformation and take it whole new level.

Schema response

You can use schema generator to generate schema for the input JSON

Schema response generate schema

Generate schema from basic JSON

Proxy response body

Copy the generated schema in the response body to generate dynamic data.

Schema response body

Proxy response

Proxy response merges multiple similar response bodies. This is very useful to call real services and make the service act as a gateway. You can introduce delays for responses if wished.

Proxy response body

Request

Matching

By default a case matches any request, this is ok for default case while for any addiontaional response cases its almost always required to use some sort of matching rules.

Default case rule

Pre processing

You can inject dynamic headers before hitting response case. The values can use any of the environment variables defined at global level.

Request pre processing

Last Updated: 9/29/2021, 4:11:03 PM
Contributors: Nithya Priya Radha Krishnan, nithyarad