Quickly Mock a Server with Localroast

One challenge commonly faced when developing against an API is the need to have a mock of the API which can be used to test the API client being developed. To solve this problem without having to go through setting up an integration environment, I created a tool to quickly mock an external API.

Introducing localroast, a command line programme that quickly starts a web server, serving mock responses for endpoints you need. All it takes is a JSON file that contains a list of mocks.

Let’s see this in an example, based on the Swagger Petstore API available at Swagger Editor. Let’s take a few APIs from this example to work on:

• GET /pet/{petId}
• POST /pet
• DELETE /pet/{petId}
• GET /user/login

First of all, install localroast via brew install caalberts/tap/localroast.

Now create a file to contain the mocks, let’s call it pets.json

[
  {
    "method": "GET",
    "path": "/pet/:pet_id",
    "status": 200,
    "response": {
      "id": 1,
      "category": {
        "id": 1,
        "name": "dogs"
      },
      "name": "Hachiko",
      "tags": [
        {
          "id": 1,
          "name": "japanese"
        }
      ],
      "status": "available"
    }
  },

  {
    "method": "POST",
    "path": "/pet",
    "status": 201,
    "response": {
      "id": 2,
      "category": {
        "id": 1,
        "name": "dogs"
      },
      "name": "Bolt",
      "tags": [
        {
          "id": 2,
          "name": "fictional"
        }
      ],
      "status": "available"
    }
  },

  {
    "method": "DELETE",
    "path": "/pet/:id",
    "status": 204,
    "response": {
      "status": "deleted"
    }
  },

  {
    "method": "GET",
    "path": "/user/login",
    "status": 400,
    "response": {
      "status": "invalid username/password supplied"
    }
  }
]

Start the mock server with localroast pets.json.

$ localroast pets.json                                                                                                           
INFO[0000] brewing on port 8080

As soon as the server is running, we can hit any of the APIs and receive the JSON response specified earlier.

$ curl -XPOST localhost:8080/pet
{ "id": 1, "category": { "id": 1, "name": "dogs" }, "name": "Hachiko", "tags": [ { "id": 1, "name": "japanese" } ], "status": "available" }

$ curl -XPOST localhost:8080/pet -D "{ \"name\": \"Bolt\" }"
{ "id": 2, "category": { "id": 1, "name": "dogs" }, "name": "Bolt", "tags": [ { "id": 2, "name": "fictional" } ], "status": "available" }

$ curl localhost:8080/user/login
{ "status": "invalid username/password supplied" }

Often, we need to keep testing between various scenarios, such as successful calls, error scenarios, bad requests, and many more. Localroast allows us to do so very easily by autoloading any changes to the file, making the change immediately available.

Say we want to test a valid login response, all we need to do is to update the login API response with a successful scenario.

{
  "method": "GET",
  "path": "/user/login",
  "status": 200,
  "response": {
    "status": "logged in"
  }
}

As soon as the file is saved, we can see the server updating automatically.

INFO[0533] file changed: pets.json
INFO[0533] parsed new schema
INFO[0533] updating router with new schema

And now we’d get the new response if we hit the login API again.

$ curl localhost:8080/user/login
{ "status": "logged in" }

I hope this tool can speed up your development workflow. Any feedback, feature requests and pull requests are welcome.

Comments

[Tarkan Nielsen]

I absolutely love the name of the project! And the tool looks extremely useful also, will most likely be using it in the future.

[Albert Salim]

Thanks! Feel free to contribute ideas and PRs :)