DuckRails - Open source development tool for mocking API endpoints

Update - Nov. 18, 2017

Please visit the updated wiki pages of the project at GitHub. This post is old and does not reflect any changes being made to the application.

DuckRails is a development tool.

Its main purpose is to allow developers to quickly and dynamically mock API endpoints.

Why mock?

Some reasons to mock endpoints:

The service you want to consume:
- is still under development
- is not available

and you don’t want to implement the mocking inside your code.

There’s also another interesting point which transforms the DuckRails from a development tool to an actual API (the tool needs a lot of improvements though in order to be used like this in production): Since the mocks can be configured to be dynamic, you can actually wrap your actual endpoint and enhance it with new data, transformations on the original data and whatever else you can think of.

Installation

First of all, you will need to clone the repo:

git clone https://github.com/iridakos/duckrails.git

Then, you have to do some basic stuff pretty common for a Rails application:

cd duckrails
bundle install

This will install all the required gems (libraries) the application needs.

You can use DuckRails either in development (quick setup) or production (better performance) mode.

Development mode

bundle exec rake db:setup

This will setup your database. DuckRails is configured to use MySQL as a database. You can change the file config/database.yml to make it match your custom database setup. Here’s a guide if this is your case.

bundle exec rails server

This will start the application in development mode.

Production mode

For production mode, you will need to do some extra steps.

Your env needs to have a SECRET_KEY_BASE variable (used to secure your sessions from tampering).

To generate a key, you can use:

bundle exec rake secret

Then export the variable with the previous’ command output.

export SECRET_KEY_BASE="your_secret_key_base_here"

Setup the database:

RAILS_ENV=production bundle exec rake db:setup

Precompile the assets (images, stylesheets & javascripts):

RAILS_ENV=production bundle exec rake assets:precompile

Start the server:

bundle exec rails s -e production

That’s all. Navigate to http://localhost:3000 and you should be seeing this:

Using DuckRails

The tool’s functionality is pretty straight forward:

you can view all your mocks
create new mocks
edit existing mocks
delete mocks

Mock configuration

Create a new mock by pressing the related button in the application home page.

There are 4 main sections allowing to configure a mock.

General

Here you can configure the general properties of the mock.

Name: a name for this mock
Description: a general description for the mock, other users using the tool may want to understand your mock and this is a good place to explain it
Method: select the HTTP method this mock matches to. This value along with the route path is going to create a unique “endpoint” serving your mock.
Status: fill in the HTTP Status code this mock will respond with upon call (you can set dynamic status, view the Advance section of this document).
Route path: fill in the path of the mock. You can use path variables, example: /authors/:author_id/posts/:post_id and these will be available later on, when you configure the mock’s body via the @parameters variable (see below).

Response body

In this tab, you configure the response’s body.

Body type: select the type of the body’s content. You can either select:
- Static: implying that the response body will always be the same, no further process
- Embedded ruby: the response’s body will be dynamic and what you fill in the Body content field will be evaluated as embedded ruby script (See the Advanced section of the document for an example).
- Javascript: the response’s body will be dynamic and what you fill in the Body content field will be evaluated as Javascript (See the Advanced section of the document for an example).
Content type: select the content type of the response. The content type can be dynamic, I will explain later on.
Body content: fill in the response’s body (static or embedded ruby depending on your previous selection).

Headers

In this tab you can add headers to the mock’s response.

add header: click the link to add new header
Name: fill in the header’s name
Value: fill in the header’s value
x: remove the header

You can set dynamic headers, see the Advanced section of this document.

Advanced

In this tab you can set some advanced configuration for the mock.

The script field is expected to be evaluated to a JSON. The evaluated JSON’s keys can have values that will override previously (un)defined values:

headers: an array of hashes with keys:
- name: the name of the header
- value: the value of the header
status_code: the HTTP status of the response
content_type: the content type of the response
body: the response body

Besides the evaluated JSON, here is the place to add code to do stuff like simulating a delay.

Here’s an example script:

<% sleep 5 %>
<%=
  {
    headers: [
      {name: 'Dynamic-Header', value: SecureRandom.uuid},
      {name: 'Foo-Date', value: Date.today}
    ],
    status_code: @parameters[:whatever].present? ? 200 : 400,
    content_type: @parameters[:format].present? ? "application/#{@parameters[:format]}" : 'text/plain',
    body: '<h1>New response body</h1>'
  }
%>

The sleep 5 above is going to delay the response for 5 seconds. The evaluated JSON is going to add two dynamic headers and set the status code & content type of the response based on the @parameters variable values.

Embedded ruby

Both in “Body content” of the Response body tab & in “Script” of the Advanced tab, you can access the following variables:

@parameters: a hash containing the request’s parameters (including the path parameters of your route)
@request: the request itself
@response: the response

Example:

Using the following code in the Response body content field:

<div>This is a text mock</div>
<h1>Author id: <%= @parameters[:author_id] %></h1>
<h2>Post id: <%= @parameters[:post_id] %></h2>

and setting your route path to:

/authors/:author_id/posts/:post_id

your mock will be served like this:

Feel free to open issues for the tool here.

If you need some help regarding the documentation, make sure to label your issue as help wanted

Table of contents