Tutorial: Intro to Restbird

Overview

We will show a basic example for each restbird core functions during this tutorial. You will get an initial impression what Restbird can do after this tutorial. For deep understanding, and use its advanced functions, please read doc and play with it after the tutorial.

The tutorial is divided into several sections:

• Setup for the Tutorial will guide you to install docker and restbird docker image.
• Rest Api Testing will show you how to do rest api testing which inclues how to build rest request and validate response.
• Recorder and replay will show you how to do http recording.
• Mock server will show how to setup a mock server.
• Task will show you how to use task in projects.
• version control will show you how to use git to manage your project files.

You don’t have to complete all of the sections at once to get the value out of this tutorial. Try to get as far as you can — even if it’s one or two sections.

Setup for the Tutorial

There are two ways to complete this tutorial: you can either do everything through the restbird web portal, or you can access the project directory to create everyting directly. To be more straight forward, we will use restbird web portal through out the tutorial.

Install Docker (for Linux/Macos/Windows)

Docker is well supported on all popular platforms, like Linux, Macos, Windows. For more detail infomation on how to install docker, you can refer the docs on docker’s wetsite. Here we take Ubuntu and Macos for examples to show how to install it :

Install Docker CE on Ubuntu

For detail infomation and system requirements about Docker CE for Ubuntu installation, plese check documents on docker website.

1. Setup the docker repository

   $ sudo apt-get update
   $ sudo apt-get install \
   apt-transport-https \
   ca-certificates \
   curl \
   software-properties-common
   $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
   $ sudo apt-key fingerprint 0EBFCD88
   $ sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

2. Update the apt package index.

   $ sudo apt-get update

3. Install the latest version of Docker CE

   $ sudo apt-get install docker-ce

4. Verify that Docker CE is installed correctly by running the hello-world image.

   $ sudo docker run hello-world

   Docker CE is installed and running. The docker group is created but no users are added to it. You need to use sudo to run Docker commands.

Install Docker on Macos

For detail infomation and system requirements about Docker-for-Mac installation, plese check documents on docker website.

Here is the basic steps:

1. Double-click Docker.dmg to open the installer, then drag Moby the whale to the Applications folder.

2. Double-click Docker.app in the Applications folder to start Docker. (In the example below, the Applications folder is in “grid” view mode.)

You are prompted to authorize Docker.app with your system password after you launch it. Privileged access is needed to install networking components and links to the Docker apps.

The whale in the top status bar indicates that Docker is running, and accessible from a terminal.

If you just installed the app, you also get a success message with suggested next steps and a link to this documentation. Click the whale (whale menu) in the status bar to dismiss this popup.

3. Click the whale (whale menu) to get Preferences and other options.
4. Select About Docker to verify that you have the latest version.

Congratulations! You are up and running with Docker for Mac.

Pull RestBird docker image

Once the docker is installed on your system. you can use the docker client command to pull out the RestBird image from the docker hub.

# pull the docker image from docker hub
$ sudo docker pull restbird/rest

Creat Project Directory and Run Restbird

When you get here, congratulations ! It means all are setup ready to run our RestBird container now.

First, before we start to run the restbird container, we need to create a project directory where all the project files will save.

The project directory can be any place, take ‘/var/my-first-project’ for example:

$mkdir /var/my-first-project
$ls /var/my-first-project

Second, run the restbird container and mapping the project directory we just created.

# run docker on host's network directly for simple (prefered)
sudo docker run -ti --user $(id -u):$(id -g) --net host  -v /var/my-first-project:/data/restbird restbird/rest

# or run docker from an isolated network on host
sudo docker run  -ti --user $(id -u):$(id -g) -p 8080:8080 -v /var/my-first-project:/data/restbird restbird/rest

Now, we can launch the browser to access the restbird portal: http://localhost:8080/ .

Tip

If docker is runing on host network directly (use —network host), we have many benefits from it, like we don’t need to mapping the mockserver port or recorder’s port to the host.we will learn it later.

The default username and password is admin/admin. Once login, here is the dashboard:

If you want to access the docker outside the pc where the docker is running, you can use http://{host-ip-address}:8080/, where {host-ip-address} is the host IP address.

Tip

read Docker’s document to learn how to map a host’s ports and directories to a container

Rest Api Testing

Now that you’re set up, let’s start rest api testing.

Create a Rest Project Case

1. login to restbird portal and switch to “Rest Project” Tab. Click ”+ New” button.

2. Create a Rest Directory (test)

3. Create a Rest Case (hello-google) under the Directory we just created

Now, the ‘hello-google’ case was created.

we supports two type languages here : Python and Golang. we choose Golang first, then we use another example to show python case.

Add Rest Api

the ‘hello-google’ case is created, it time to add a rest api to test it.

1. login to restbird portal and switch to “Rest Project” Tab. Click ”+ New” button to add a rest api (Actually could any http request).

2. Click the api to see the detail, and modify all the field to build the http request.

• swith the tabs under the api to provide the Url and methods, Authentication, HTTP Header, Request Body for the http request.
• Pre-Request is a block of Script you can provide to advanced build the http request just before we send it. We can overwrite any infomation provided by the above tabs, and can also provide additional info to build the http request.
  
  In this example, we don’t do any advanced building of the http request, so just leave the “Pre-Request” block as empty.

• Response Check Script is a block of Script you can provide to check the Http Response we get after the execution.
  
  In this example, we just simpley check if the response satus code is 200.

Run Rest Api

There are two ways to run a created Api.

1. while the Api development phase, we normally click “Run Test” button under a api to run that api and check the result.

2. when all Apis are created, we could select a group of Apis and click the “Run Selected” button on the page to run this group of api.

Check Rest Apis Running History

No matter you click “Run Test” to run a specific Api, or you click “Run Select” to run a group of Apis, an entry will be created for each running to record the detail of the Http Request and Response.

Using Varibles during Api Building

Instead of building the request staticly, we can use varibles while building a HTTP Request. This is advanced topic, please refer the Doc for the detail infomation.

Recorder and Replay

Now that you’re set up, let’s play restbird recording functions.

Create a Recorder Project Case

1. login to restbird portal and switch to “Recording” Tab. Click ”+ New” button.

2. Create a Recorder Directory (test)

3. Create a Record Case (github) under the Directory we just created

Now, the ‘github’ case was created.

Setting Recorder

Once the recorder case is created, we need to specify the target(url) we are going to record and the local proxy port we are going use. Click the “setting” to do the setting before we launch our recorder.

In this example, we will record https://github.com, and local proxy port is 8889.

Tip

Restbird recorder is implemented through reverse proxy. Please check the Doc for the backgound principle of it.

Do Recording

It is the time to click “Start” to button to launch the recorder now. But before we do that, we must make sure to map the proxy port(like 8089 in this example) to the host, or we can not access the proxy url.

1. map the proxy port from container to host (skip this part if you already do that when you start the container).Stop the restbird container and start a new one by mapping the proxy port:

sudo docker run    -ti    -p 8080:8080 -p 8089:8089   -v /var/my-first-project:/data/restbird    restbird/rest

Best Practice

the best practice is when we start the container, we map a set of ports at that time, like: sudo docker run -ti -p 8080:8080 -p 9000-9100:9000-9100 -v /var/my-first-project:/data/restbird restbird/rest

2. click “start” button and access the proxy url

3. do recording through the proxy url

4. check the recorded http requests by click the “refresh” button. Click the recorded Api will see the detail of the http request and response.

Copy to Rest Project/Mock Server

The recorded Apis could be copied to a Rest project case to replay it or a Mock Server case to set up the initial mock server apis.

For more detail infomation, please check Doc.

Mock Server

Now that you’re set up, let’s play restbird Mock Server functions.

Create a Mock Server Project Case

1. login to restbird portal and switch to “Mock Server” Tab. Click ”+ New” button.

2. Create a Mock Server Project Directory (test)

3. Create a Mock Server Case (hello) under the Directory we just created

Now, the ‘hello’ mock server case was created, and let’s choose ‘Javascript’ as the programing language at this time.

Setting Mock Server

Once the Mock Server case is created, we need to specify the server port where we will listen to the http requests. Click the “setting” button to do the setting before we launch our mock Server.

In this example, we will listen to port 8088.

Tip

Restbird Mock Server supports three programming language: Java Script(based on nodejs express), Python, and golang. Please check the Doc for more detail introduction.

Add Mock Api

the ‘hello’ mock server case is created, it time to add a mock api before we launch the mock server.

1. Switch to “Mock Server” Tab and select the mock server case, then click ”+ New” button to add a mock api.

2. Click the api to see the detail, and provide the response in two ways(simple response or advanced response).

• simple response, in this mode, we will build up the response staticly by providing the status code, res header and res body.

• Advanced Request Handling, in this mode, we do programing to handle the incoming request and send response.

Run Mock Server

We just added a mock api, it is the time to click “Start” to button to launch the Mock Server now. But before we do that, we must make sure to map the mock server port(like 8088 in this example) to the host, or we can not access the mock server in the container.

1. map the server port from container to host (skip this part if you already do that when you start the container).Stop the restbird container and start a new one by mapping the server port:

sudo docker run    -ti    -p 8080:8080 -p 8088:8088   -v /var/my-first-project:/data/restbird    restbird/rest

Best Practice

the best practice is when we start the container, we map a set of ports at that time, like: sudo docker run -ti -p 8080:8080 -p 9000-9100:9000-9100 -v /var/my-first-project:/data/restbird restbird/rest

2. click “start” button and we can access the mock api at ’http://localhost:8088/helloworld’

Mock Server State(DB)

Sometimes we might requrie to save data on mock server, and the data is shared and accessable by all mock api requests. This is fully supported by two programing interface(state.save/state.get) in “advanced request handling” mode:

Here is an example code block:

function HandleRequest(req, res, state) {

    var statecount = state.get("counter");

    if (statecount) {
        statecount.count  = statecount.count + 1;
        state.save("counter", statecount);
    } else {
        statecount = {
            count: 1
        };
        state.save("counter", statecount);
    }

    res.send('hello, I am advanced Request handler:'+ statecount.count);
}

module.exports = HandleRequest

Task

Task is a very flexible part of restbird. You can consider each task as an independent program that you could implement thorugh golang or python. And you can do anything there, like system monitor, run a rest project cases/apis, start/stop mocker server, do loading, send email alerts.

Create a Task

Todo …

Run a Task

Todo …

Version Control

As described, all the restbird project files are saved in the host folder that you mapped to the restbird container. So you can directly edit the files in the folder through your favorite code editor and can also manage the project files through git, svn. This is extremely usefuly for continuous development or team corporation.

The project files for this tutorial has following hirachy:

$cd /var/my-first-project
$tree .
├── library                      # all third party libraries for golang 
├── libraryPy                    # all third party libraries for python
├── libraryJs                    # all third party libraries for javascript
├── projects
│   ├── examples                 # all programming example/snips for golang/python/javascripts are here
│   ├── mock                     # all mock server project cases are under this folder
│   │   └── test
│   │       └── hello
│   │           ├── api0         # define the mock api #0  
│   │           │   ├── mock.js
│   │           │   ├── req.json
│   │           │   └── res.body
│   │           ├── api1         # define the mock api #1
│   │           │   ├── mock.js
│   │           │   ├── req.json
│   │           │   └── res.body
│   │           ├── mock.json
│   │           ├── mocktask.js
│   │           └── type.json
│   ├── record                 # all recorder project cases are under this folder
│   │   └── test
│   │       └── github
│   │           ├── record.json
│   │           └── type.json
│   ├── rest                  # all the rest project cases are under this folder
│   │   └── test
│   │       └── hello-google
│   │           ├── api0     # a rest api definition of case 'hello-google'     
│   │           │   ├── prerequest.go
│   │           │   ├── req.body
│   │           │   ├── req.json
│   │           │   └── resval.go
│   │           ├── api1
│   │           │   ├── prerequest.go
│   │           │   ├── req.json
│   │           │   └── resval.go
│   │           ├── api2
│   │           │   ├── prerequest.go
│   │           │   ├── req.json
│   │           │   └── resval.go
│   │           └── type.json
│   ├── task             # all tasks definitions are under this folder
│   └── user             # restbird portal admin/user are defined here
├── state                # all runing history and mock server state(DB) are under this folder
└── version.json         # restbird version infomation

git

if the project folder is already under a git managed folder, it is pretty eady to get it managed

$cd your-project-folder
$git add .
$git commit -m "some messages"
$git push

if you would like to setup a git repository for this project files directly. Please refer git documents

svn

Todo …