genie-oh

Posted on Apr 3, 2022

Thinking about making external API to Mock API Server with Mockoon

#mock #mockoon #api #mockserver

Thanks for your visiting.
I glad if you understand that my english level is beginner.
I would be very happy if you find and tell me any mistake made by me.

0. outlines

Integration of external API services in web services can greatly improve productivity and provide chance to make new value. but, due to the limitation of environment and specification provided from that services, I think you have various difficult experiences in maintenance and repair on integration development and continuously integration and testing.

In this article, consider "How to make an external API to MockAPI to make software to more easier on testing, operating and maintain?".

This article sections are

1. Introduce Mockoon (Mock API Server)
- describe about Mockoon simply
2. Mockoon TIP
- describe useful tips to use MockAPI more helpful
3. Manage MockAPI on code-revision and launching on Docker
- describe how to use it on team-development by code-revision management and docker environment
4. Discussion about doing introduction of it
- describe about that -why we need?, what positive effects are?, what options are?, why choice it?-
5. Conclusion

※ If you already have the experiences about Mock API Serveror know it, you can start to read from section 4.
※ This is NOT actual example. this is based on pre-investigation & discussion before actual introduction to team-development.
※ Please notice that this article contains many subjective opinion of me. I will be happy for you to send it to me if you find wrong things or other opinions.

1. Introduce Mockoon (Mock API Server)

On this section, describe steps of installation and running with simply test about Mock API Server.

I want to you gain the sympathy of that How to easy adding and modify Mock API for simulating and testing.

1-1. what is Mockoon?

Mockoon is one of API Simulating Solutions(Tools).
it is ok to say to Mock API Server Solution.

it provide methods of making HTTP protocol based API features and server on Mockup Level more simply.

1-2. installation

you can use brew if you use MacOS.

brew install --cask mockoon

you can refer installation about other environments on official references.
https://mockoon.com/download/

1-3. run Mock API Server on local environment

You can run Mockoon after installation.
at the first run, Demo APIs are provided as default.

You can try to connect & see results on Demo API's to Start Server on toolbar or menu.

1-4. try to connect & see result

This image presents that Server is running.
try to connect to /users in Demo API.

you can find 0.0.0.0:3000 is API Server's host&port from left side of program window. it is mean that you can connect as http://localhost:3000/users. so, try it and see results.

❯ curl -v http://localhost:3000/users
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 3000 (#0)
> GET /users HTTP/1.1
> Host: localhost:3000
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Content-Length: 4393
< Date: Mon, 21 Mar 2022 07:00:21 GMT
< Connection: keep-alive
< Keep-Alive: timeout=5
<
{
  "Templating example": "For more information about templating, click the blue 'i' above this editor",
  "users": [
      {
        "userId": "16861",
        "firstname": "Jerry",
        "lastname": "Simonis",
        "friends": [

# ...skip

and, you can see logs on Mockoon GUI that contains request informations.

just like it, we can see API Results of Demo API.
and at this time, it has been prepared that we make Mock API using Mockoon.

1-5. Add Custom Environment and Mock API

in this part, show steps of adding Environment and MockAPI, saying how to make API and what basic features are.

1-5-a. Add new Environment on Mockoon

Environment mean that specifications of definitions of Mock API and Server. it's ok you recognize as One Project File of Mockoon.

like the gif, we can make new environment.

and, we can run server and connect new environment because API having path / and response {} is generated as default.

❯ curl http://localhost:3001
{}

1-5-b. Add Mock API (set Route, Header, Body)

Try to add Mock API that has /hello route path and will response world with text/plain Content-Type Header.

steps are

click new route in menu bar
set hello on the path at right up side.
set world on the body at right down side.
set Content-type: text/plain at Headers TAB.

I can added Mock API easily.

1-5-c. test API

try to make request to http://localhost:3001/hello.
you can see successfully connected & received response from mock API.

❯ curl -v http://localhost:3001/hello
# ...skip
< Content-Type: text/plain; charset=utf-8
< Content-Length: 5
# ...skip
world

2. Mockoon Tips

I have told how to make MockAPI with very simple case.
I think it is very easy to make MockAPI with Mockoon. I glad if you have same thinking.

But, we need to more features to develop services although objective are simulating and testing.

so, in this parts, introduce helpful tips to add and modify Mock API more simply, more widely.

2-1. Routing

Mockoon provides some features about Routing of URI path.
if you want, can see it at below official document.

https://mockoon.com/docs/latest/routing/

2-1-a. API route prefix

Common prefix is provided that effects entire path on one environment.

it can setted on Settings->API URL->prefix.

2-1-b. Route Patterns

Pattern Matching on uri path is provided like ?, +.
it will be possible to dynamically perform like various path by one defining.

the expression is follow express.js specs.

2-1-c. Route Parameters

parameter using uri segmentation is provided.
can use by defining /:parameter_name on route path.
can get and use by defining {{urlParam 'paramName'}}.(feature of templating on Mockoon)

2-1-d. Query Parameters

can use QueryString as Parameter

can get and use by defining {{queryParam 'paramName'}}.(feature of templating on Mockoon)

2-2. Helpers

Mockoon provides more feature as Helper to make Mock API more dynamically and widely.

to use helpers on response body or others, we need to call following template likes {{helperName param1 param2}}.

Helpers consist of parts of HandleBars Helper, Mockoon Custom Helper, Request Helper and faker.js Helper.

2-2-a. HandleBars Helper

Mockoon provides features of HandleBars.
so, you can use expression of if, else, each, with and others provided by HandlerBars.

more informations, please refer to
https://handlebarsjs.com/guide/builtin-helpers.html

2-2-b. Mockoon Custom helper

Custom Helper provide by Mockoon.
you can use utilities related Array, Math, String, Date and others.

more informations, please refer to
https://mockoon.com/docs/latest/templating/mockoon-helpers/

2-2-c. Request Helper

can get and use request informations likes body payload, query parameter, cookie, host information and others.

more informations, please refer to
https://mockoon.com/docs/latest/templating/mockoon-request-helpers/

2-2-d. faker.js Helper

Mockoon provides faker.js features.
it is helpful to generate random informations of e-mail, name, address and others.

more informations, please refer to
https://mockoon.com/docs/latest/templating/fakerjs-helpers/

2-3. Other features.

Mockoon provides various features likes File Serving, TLS, CORS, Multi Response and others.

more informations, please refer to
https://mockoon.com/docs/latest/about/

3. Code-Revision management and Running on Docker

In this section, try to know that how to share Mock API and Environment to team and use more efficiently.

3-1. Code-Revision Management of Mockoon Environment File

Environment File is that presents specifications of MockAPI and Server as i said earlier.

it follows JSON format.
if you see contents of file we make on section 2, we can find that '/hello' API and Server specifications is described.

so, we can manage it on Github or other code-revision-management-solutions.
it help us to use Mock API Server more efficiently on team-development projects.

❯ cat test-mockoon.json | jq
{
#...skip
  "port": 3001,
  "hostname": "0.0.0.0",
#...skip
  {
#...skip
      "method": "get",
      "endpoint": "hello",
      "responses": [
        {
          "uuid": "7e4e0df8-5b58-4655-98dc-dc912009f665",
          "body": "world",

3-2. Running Mock API Server on Docker with a Environment file we made.

It may be inconvenient that installing and using GUI of Mockoon on all team members.

fortunately, Mockoon provides docker image for running and testing api made by it.

just like below, we can run it with local environment files or file's url of github repository .

# using local file path
docker run -d --mount type=bind,source=/absolute/path/to/data.json,target=/data,readonly -p 3000:3000 mockoon/cli:latest -d data -p 3000

# using file's url of github repository
docker run -d -p 3000:3000 mockoon/cli:latest -d https://raw.githubusercontent.com/mockoon/mock-samples/main/samples/generate-mock-data.json -p 3000

you can refer more specific informations at below.
https://mockoon.com/tutorials/run-mock-api-anywhere-cli/

3-3. testing API with running with Docker

try to run server using docker with environment file we make at section 2.

below presents result of it.

❯ head test-mockoon.json
{
  "uuid": "0415ae77-0fe7-4baf-b92b-07819280d4d6",
  "lastMigration": 19,
  "name": "Test",
  "endpointPrefix": "",
  "latency": 0,
  "port": 3001,
  "hostname": "0.0.0.0",
  "routes": [
    {
❯
❯ docker run -d --mount type=bind,source=/Users/oh/Develop/test-mockoon.json,target=/data,readonly -p 3001:3001 mockoon/cli:latest -d data -p 3001
de956b5a8b15415b5c46ff008d5b0db404a5d2670055fde14cf6621d0746821b
❯
❯ docker ps
CONTAINER ID   IMAGE                COMMAND                  CREATED              STATUS              PORTS                    NAMES
de956b5a8b15   mockoon/cli:latest   "mockoon-cli start -…"   About a minute ago   Up About a minute   0.0.0.0:3001->3001/tcp   goofy_cohen
>

❯ curl http://localhost:3001/hello
world
>

3-4. About using more efficiently on Team-Development

I think it is good on developing on team that using Mock API Server. just like below.

define Mock API and Environment using Mockoon
push to Github Repository
share it to team
each member, try to run Mock API Server using Docker command with environment file url on Github Repository

it will be useful because we can use same Mock API environment on all members.

4.Discussion about doing introduction of it

in this section, say about introduction of Mock API Server by below 3 points.

Why we need to make external API to Mock API Server?
What positive effects are?
What other options are? Why choose Mock API Server as solution?

4-1. Why we need to make external API to Mock API Server?

To cut off strong coupling of them
that is important purpose of making it to mock.

In now, integrating external API to our services have been necessary.

for example, we use it frequently that social login, payment gateway, e-mail sending, service monitoring and others for user convenience or business strategy.

it is very valuable things because we can deliver value to user that we can't it by only our's power originally.

But, I think integrating of external API may make some annoying features like below.

features that has very strongly coupling with external API on our services. (it may make testing and separation of concerns to hard)
features that are very difficult for us to control. (API provider has all ownership.)

it will be negative factors on maintaining software quality and developing as team.
so, we need to discuss about -How we cut off coupling of them and make maintaining and developing to be easy-.

-Mock API Server- is one solution for that question.

4-2. What positive effects are?

say two points in many things may are.

a. improvement development productivity as team
b. improvement usability about CI and Auto-Testing

4-2-a. improvement development productivity as team

I think it is problem we meet commonly on integrating external API.

Waiting time about preparing API environment from Provider.
Limitation of access to API
Mis-matching understanding about API specs between team members.

I think that pre-developing of Mock API will relief it because we can try to cut off coupling of them and manage API specs with centralizing.

4-2-b. improvement usability about CI and Auto-Testing

We can regard Mock API Server as stand-alone service.
so, we can try to cut off coupling between application and mock logic almost perfectly unlike MockClass or MockLibrary.

due to it, we can expect below

Can make as coverage on Auto-Testing and CI
Can separate concerns about application and mock logic. so, it will make adding and modifying of software to more easily.

it will relief our burdens about existing problems we have met on CI and Auto-Testing.
and, it will be make maintaining software quality to be more efficiently.

4-3. What other options are? Why choose Mock API Server as solution?

i think there are below solutions generally.

① （choice） Mock API Server
② DON'T make mock. exclude it from coverage of auto-testing.
③ make MockClass
④ use Mock Library with separating layer about business logic.

4-3-a. The reason of choosing Mock API Server

in options, I think Mock API Server has nice merit compare with others.

Very easy to add and modify Mock API.
Can separate concerns almost perfectly between application and mock logic.
Very helpful to make understanding to be equalative in team-members.
Very helpful to manage and maintain of informations.

4-3.b. What problem are in others?

■ ② DON'T make mock. exclude it from coverage of auto-testing.

It may frequently things in development.

I think The reasons are

Need more times for developing.
Level of difficulty about it.

but, Mock API Server is specialized solution to make it with very small times and very simply.

if we don't it although it's easily and simply, we may lose nice opportunities that brought by mock.

■ ③ make MockClass, ④ use Mock Library with separating layer about business logic

this options have merit that we can develop freely.
but, i think it has below problems may annoy to us for long time.

Burdens about developing Mock Logic
Level of Difficulty about software design, developing, maintaining software quality

actually, the method of ③ is always needed concerns of maintaining clean architecture using knowledges of OOP, Design Patterns -for examples, making Provider Class likes Factory, design class relationship with Dependency Injection-.

additionally, about ④, may be needed DDD design knowledges for separation of layer of business logics.

if we don't do it, we will meet more annoying problems about badly software quality than that we don't make mock.
and, it will be more difficulty problems if we develop software as team.

i think one key reason is -strong coupling between application and mock logics.

we can cut off coupling about external API system to develop mock logic.
but, it may make new problem that make newly coupling between application and mock logic. and it will make developing more hardly because we need to think same concern about application and mock logic.

it may not problem if service is micro.
but, it will increase very rapidly according to be bigger of service. I think that's very difficulty problem to us.

5. Conclusion

We would try to it because it will be bring nice merits about developing as team, maintaining software quality if we need to integrate external API and we need to service continuously

that's my conclusion.

of course, it may has some problems and don't solve all problems. for example, it may are that -cases we can't solve using it, handle to exceptional cases, increase management point about service-.

but, I think merits are bigger than de-merit.

actually, i have met many problems with developing and operating complicated service that integrated with several external API to one service and has served for long term and is monolithic service.

By Introducing Mock API Server, we can try to -cut off coupling about external API- and -make developing as team, Auto-Testing, and CI to be more efficiently-.
so, I expect that it contributes to refactoring of monolithic service architecture with improvement of development.

References

I have referred below for studying it.
please refer to if you have interesting about it.

https://en.wikipedia.org/wiki/Comparison_of_API_simulation_tools
https://developers.amadeus.com/blog/helpful-tools-to-create-mock-servers