MockiMouse, Easy To Use Mock Server To Build Fake Dynamic API

Sometimes developers face a situation in which they are approaching the deadline of project demo, but the back-end is unlikely to be done before the deadline. It may happens to you that you are working on a front-end project which the back-end API is not ready to serve the request you from front-end. MockiMouse is an easy to use, and an easy to run mock server that helps you make dynamic fake API to test or demo your front-end project without waiting for back-end team to deliver the real APIs you need. In a few lines of YAML file you can config your fake server to generate fake response data and start serving requests coming from front-end. You can find the project and its binaries on its github repository.

Download win64 binary of MockiMouse from here

Source code on Github :

Let’s go to the point! First, I start from a simplest possible case where we want to mock two simple API that always send same response to client. Open config.yml file and past below configuration in it, then start the server:

MockServer :
 port : 800
 endpoints :
  - name : Hello world endpoint
    path : /hello
    method : GET
    scenarios :
     - description : no condition, always show same message
       response: 
         - Welcome to Hello world 
  - name : Goodbye endpoint
    path : /goodbye
    method : POST
    scenarios :
     - description : no condition, always show goodbye
       response: 
         - Goodbye. See you later

As you can see The config starts with MockServer root, then with port parameter you can choose on which port you want to start the mock server. That’s not the only parameter you can set for the server, the contextPath for APIs and staticFilesPath are to other optional parameters of server :

• contextPath : With this parameter you can place a prefix path part for all APIs. For example you can put /api in path to all endpoints. Then endpoints would be exposed like server-address:port/api/yourEndpoint
• staticFilesPath : Besides the MockiMouse.exe, you can find a folder named assets. Static files that you put in this folder can be accessed under server-address:port/assets/ path, e.g server-address:port/assets/photo.jpg. With staticFilesPath parameter you can change the path to these files.

Then in endpoints parameter which is an array, you can declare endpoints and their specifications. Every endpoint accepts following paramters :

• name : It’s an arbitrary title you can choose for your endpoint
• path : It’s the path to call endpoint. You can also define path parameter with colon prefix like /person/:personId or /api/product/:id/history
• accepts : It’s an optional parameter that you can use to restrict the client to send specific content-type such as application/json , text/plain, application/xml. You can set multiple content-type separated with space. If the parameter be omitted , no restriction will be placed on the requests.
• method : As the parameter name is clear, it define the HTTP method of the endpoint, MockiMouse supports GET, POST, PUT, PATCH and DELETE methods. This parameter is mandatory.
• delay : With delay parameter you make the endpoint to wait N millisecond before responding to client. It’s optional and the default value is 0.
• scenario : The last and most important parameter of endpoint which I describe it in this article.

So, a sample endpoint configuration can be like this :

MockServer :
 contextPath : /api  # a prefix path for all endpoints
 port : 800
 endpoints :
  - name : Login endpoint
    path : /login # the actual address of endpoint is 127.0.0.1:800/api/login
    accepts : application/json text/plain
    method : POST
    delay : 3000
    scenarios :
     ...

  - name : Logout endpoint
    path : /logout # the actual address of endpoint is 127.0.0.1:800/api/logout
    accepts : application/json 
    method : GET
    delay : 1000
    scenarios :
     ...

Scenario

Scenario is combination of one or several conditions that result to specific response. For example, in login endpoint we have two scenarios.First scenario is when client send valid username and password to the endpoint, and second scenario is when client send invalid username and password to the endpoint. For each of these two situations, we can send corresponding response. It helps front-end developer to test all possible scenario of it’s project. Let’s see what happens in yaml config for described scenarios :

MockServer :
 contextPath : /api
 port : 800
 endpoints :
  - name : Login endpoint
    path : /login
    accepts : application/json
    method : POST
    delay : 3000
    scenarios :
     - description : When credential is valid
       condition :
         param :
            - name : username #paramter name
              type : body
              operand : equal 
              value : admin
            - name : password
              type : body
              operand : equal
              value : 1234
       response: 
         - file://helloWorld.json
         - url://some-addresss/path/to/hi.json
       
     - description : When credential is invalid
       condition :
          param :
            - name : username
              type : body
              operand : equal
              value : admin
            - name : password
              type : body
              operand : notEqual
              value : 1234
       response : 
         - file://invalidCredintial.json
       status : 200

Here the art of MockiMouse starts. Except the scenario part, we are familiar with above configuration. The scenario consist of a condition that a request should meet to trigger that scenario. The condition may involve one or several parameters. For example, in the above configuration, for valid scenario, we need the client to send “admin” as username and “1234” as password. So, I declared two parameter and their expected value in condition part of scenario.

       ...
       condition :
         param :
            - name : username
              type : body # it means the username is a post body json parameter
              operand : equal # it means we need the username be equal to following value
              value : admin
            - name : password
              type : body
              operand : equal
              value : 1234

       ...

So each param takes following paramters :

• name : The name of parameter. For JSON parameters it can be a path like order.id or student.birthplace.city
• type : MockiMouse gives access of all kind of parameters to let the fake API behave exactly like it’s real one. You can retrieve parameters from header, form, query, body and path. I think they don’t need further explanation. Just set the type of param to one of these keyword to get the value of parameter in the by its name.
• operand : It’s not like that in every condition we only want the parameter to be equal to a value. We also need notEqual, greaterThan, lessThan, greaterEqual, lessEqual, contain.
• value : It’s the value that we want to compare the parameter with it.

After specifying the condition in the scenario with its parameters, we can say which response and what kind of response to send as response. We do it by response, status and contentType parameters.

• response : It accepts list of response. Each of response in the list can be text, file or url. To read the response from the file, just add file:// prefix to the response value like : file://jsonProducts.js, or http://anyserver.com/resp.xml to read from a remote url. It should be notice that if you want to read from the file, you should place the file in the responses folder of MockiMouse beside the server executable file. If your response list contains more than one response, each time the scenario matches, it will choose a response from the list randomly.
• status : The status parameter accept all status code, and its default is 200.
• contentType : accept all possible content type such as text/html, application/json, application/xml and etc.

Finally, to run the project, just run the executable mockimouse.exe, if you have done the configuration well you should see the below message :

Dockerizing The Mock Server

You can build source code of MockiMouse and make a docker image serving as a mock server using docker file :

FROM golang:1.19

# The exposed port should be changed to port number you specified in MockiMouse config.yml
EXPOSE 800
WORKDIR /MockiMouse

# Copy source code to working directory
COPY . .

# Build source code to mockimouse binary
RUN go build .

# Start MockiMouse server
CMD ./mockimouse

You can deploy it beside your frontend container with docker compose, or even deploy it on a cloud base infrastructure to serve your frontend demo project.

Hope you find this mock server useful. If you liked it please don’t forget to give it a star on github