Support page for - Automating and Testing a REST API.
Automating and Testing a REST API
A Case study in REST API Testing and Automating using: Java, RestAssured, Tracks, Postman, cURL and HTTP Proxies
This 200+ page e-book documents a case study of testing and automating a REST API based application.
It covers interactive testing of the application through the GUI, and via cURL and HTTP Proxies.
And automating with Java and REST-assured.
Comprehensively documented, with full source code available, you’re sure to learn something new.
This is the support page for the book with links to the source, tools and the free supporting videos mentioned in the text.
- 20190225 - added a video showing how to install tracks via Docker and run the code
- 20180412 - added a video showing how to install and use the source code for the book
- 20180409 - amended the code for Java 1.9 - had to update to version
3.0.7and add some additional maven dependencies in the pom.xml
- 20180324 - added videos showing how to install cURL on windows
- 20180323 - added video showing how to install the Turnkey Tracks VM into Virtual Box
- 20170909 - added text description of the steps I used to run from Turnkey VM
- 20170804 - update, Bitnami have discontinued their VM and workaround for Turnkey Icon isses
Tracks is an open source application written in Ruby on Rails which implements the David Allen “Getting Things Done” time management methodology.
My current recommended approach is to use Docker,
- docker instructions (see video below)
- getontracks.org/downloads aboutbitnamitracks
- Bitnami Tracks Installer
Virtual Machine Software
Prebuild Tracks Virtual Machines
- Turnkey Tracks
- Bitnami Tracks
- if you are experiencing issues with GUI icons then see this workaround
You can install cURL on windows using:
- one click installer from http://www.confusedbycode.com/curl/
- chocolatey using
choco install curlhttps://chocolatey.org/
- the official site https://curl.haxx.se/ (use the download wizard https://curl.haxx.se/dlwiz/)
see the videos below for each of these installation approaches
The easiest HTTP Proxies to use are:
You could also use:
You can find information about
- REST Wikipedia page
- An overview REST tutorial at restapitutorial.com
- Roy Fielding defined REST in his Ph.D. Thesis, you can read it as a .pdf
REST API Tools
Tools not used in the case study:
- Insomnia.rest cross platform desktop REST client
REST Java API Libraries
The case study uses REST-assured:
Other libraries are available:
Lists of APIs to Experiment With
Fake APIs - i.e. these are api endpoints which serve canned data and responses
- https://swapi.dev/ - (GET requests only)
Lists of APIs (primarily of use to see different api styles and approaches)
APIs designed for testing against
The source code for all the Java code used to automate Tracks as part of the case study is available on Github
There is a video below showing how to install and use the source code.
The Postman Collection for the case study is available in the above source code and shared on the Postman site:
- From Github
- From Postman - getpostman.com/collections/b9e81b009bfd21ec5e83
- As a bit.ly - bit.ly/2iPaxgj
I created supporting videos for some of the chapters and sections in the book. These make most sense when read in conjunction with the book but offer a visual insight into tools used which the book can’t cover quite as well.
- Installing Tracks using Docker
- Installing Tracks and using a virtual machine
- An overview of Tracks GUI
- Installing cURL for Windows
- An overview of REST interaction with CURL
- Using HTTP Debug Proxies as part of your REST testing
- Using HTTP Debug Proxies with Docker and Localhost
- Using HTTP Debug Proxies as Fuzzers to Create Data
- An overview of the Postman GUI client
- Using Postman GUI Client with an HTTP Proxy
- Installing and Using the Java Source Code
Installing Tracks Via Docker
This is easy to install using Docker and this video shows the process in action.
- You need to setup a Docker account at https://docker.com
- follow the instructions on the hub page
docker pull staannoe/tracks docker run -d --name=tracks -p 80:80 staannoe/tracks
Then visit localhost:80, create an admin account.
- Youtube: youtu.be/BAExBxmlPeY
Installing Tracks Using a Virtual Machine
Installing Tracks to a VM using Turnkey.
The last time I used the Turnkey VM I used the VMWare Player 12 and used the following steps:
- download the VM (.ova file)
- using vmware workstation 12 player
- “Open a Virtual Machine” - choose the .ova file
- … vmware player spends some time importing the VM…
- run VM
- change password for root and MySql e.g. Pa55Word
- skip hub and password setup
- skup security updates
- change VM to use HOST-only private network or Bridged Adapter
- select to use DHCP for network config
- note the IP address shown in the dialog e.g. 192.168.222.129
- tracks should be running on this IP address visit http://
Note: The Bitnami install mentioned has been discontinued,read more information here
- Youtube: youtu.be/8rgZOv-yKsY
An overview of Tracks GUI
- Youtube: youtu.be/QK3eK2X4eUA
Installing cURL for Windows
Install cURL using one click installer from confusedbycode.com
Install cURL using chocolatey
Install cURL from official site on Windows
An overview of REST interaction with CURL
- Youtube: youtu.be/XT351ZmeKto
Using HTTP Debug Proxies as part of your REST testing
- Youtube: youtu.be/eAy4Xi3_xM4
Using HTTP Debug Proxies with Docker and Localhost
- Youtube: youtu.be/LjyLOgC3OjM
Using HTTP Debug Proxies as Fuzzers to Create Data
- Youtube: youtu.be/xWpuAtlb1oU
Postman REST GUI Client
An overview of the Postman GUI client
- Youtube: youtu.be/-3d4LapMrVo
Using Postman GUI Client with an HTTP Proxy
- Youtube: youtu.be/yUPg0dh0mow
Installing and Using the Java Source Code
- Youtube: youtu.be/NrDHvu5ewLo
In the video I show:
- Visiting https://github.com/eviltester/tracksrestcasestudy
- Download the
mvn clean testin the unzipped folder to download the dependencies
- Open the
- Accessing tracks from the VM
- Change the config in
- Running test data setup tests in
- And I discuss how to can resolve some common setup issues
Other Blog posts and information you might want to read related to the material in the book, I include a lot of extra references in the book, but these were found after publication and I did not want to keep adding more links into the book, so I added them here instead, I also included a few from the book:
Blog Posts and Sites:
- My Basic and Advanced REST API Workshop material this uses a different target application with different code examples.
- Bas Dijkstra’s Open Source API Workshops
- Testing REST Endpoints Using REST Assured by Kostis Kapelonis
- Mark Winteringham has a lot of useful Postman and REST information on his site here are some examples:
- Danny Dainton’s All Things Postman Github Repo
Ebook on sale at leanpub has had the following releases:
- first release of the ebook
- second release of the ebook
- fixed some grammar errors throughout text
- fixed spelling errors found throughout text
- added an example in the “cURL Summary” chapter
- added an introduction chapter “Introduction to APIs” on various web terminology - what is HTTP, what is an API, what is REST, what are HTTP headers, etc.
- expanded text in “Exploring The Tracks API with cURL through a Proxy”
- expanded text in chapter “Exploring Tracks API with Postman REST Client”, added info on using with Proxy for Mac
- added ‘Summary’ to end most chapters
- split introduction into 3 chapters to allow for the API introduction
- expanded the cURL case study chapter to have more information on cURL and what it is for, rather than diving straight into the technical stuff
- added more explanatory notes in the cURL chapter “Case Study Example Using cURL on Tracks”
- added a new chapter providing an overview of the Tracks 2.3.0 testing before diving into the details “The Case Study Overview - Testing Tracks v 2.3.0”
- added A new chapter, with a new package in the code, covering JSON and XML processing with REST Assured “REST Assured JSON and XML Processing”
- expanded the summary chapter on REST Assured “Summary of REST Assured” to cover serializing and deserializing
- about 50 new pages of material added
- additional grammar and spelling errors fixed throughout
- increased dpi of images in readiness for paperback edition
- split the ‘sample code’ chapter out of the ‘install’ chapter and moved to immediately before the ‘starting to automate’ chapter
- paperback edition on hold until I amend the install and VM chapter to cater for bitnami discontinued VMs
Paperback edition currently in proof creation and review mode. Will be the same as the 2017/07/03 release.
On 4th August 2017 I was told that Bitnami had discontinued the Tracks VM and self contained install.
This is unfortunate as I found it the most reliable and easiest way of getting started. Turnkey is now the simplest way of getting started.
I emailed Bitnami, just in case they could reinstate the installs but on 8th August I learned that the installs would not be reinstated. I suspect the following links will forever remain ‘discontinued’.
You should probably use Turnkey Tracks installers and VMs (but see the additional information below).
Using Bitnami VMs
You can still use Bitnami VMs but you have to install Tracks yourself. The following instructions are the steps I took to install Tracks into the Bitnami Ruby Infrastructure VM.
- make sure that the VM can access the outside world e.g.
curl https://eviltester.comprior to following any steps
- I switched off my local firewall for 30 mins while doing this (I haven’t added VMWare to my firewall since I changed my local firewall software)
- follow install instructions for tracks
- make a note of the ip address on the start screen 192.168.199.129
- if you miss the IP Address then when you are logged in you can type the following to show it
ip addr show
- if you miss the IP Address then when you are logged in you can type the following to show it
- following the install instructions from tracks
sudo gem install bundler
git clone https://github.com/TracksApp/tracks.git
bundle install --without development test
cp database.yml.tmpl database.yml
cp site.yml.tmpl site.yml
database.ymlto use the sqlite3 lines
- don’t really care about the security so I didn’t amend site.yml
cd ..to move to the
- precompile the assets
bundle exec rake db:migrate RAILS_ENV=production
- open port 3000 in VM
- I change VM to local network (Host-only) to avoid firewall issues 192.168.245.128
- start app with
bundle exec rails server -e production -b 0.0.0.0 -p 3000
-b 0.0.0.0to map to external facing ’localhost’
Turnkey Icon Workarounds
Stas Wasserman was kind enough to describe some additional information and workarounds on the Turnkey install:
- The option of using Turnkey is available, with a minor, but quite annoying issue in Tracks UI.
- (I know, the problem is not related to API, but it makes Tracks UI exploration a bit puzzling)
- This issue is with missing icons in Tracks from Turnkey. For example, the start and the edit icons are missing for existing actions in a project (you can see the missing resources error in a browser dev console).
- The issue is mentioned here: turnkeylinux.org/forum/support/20130805/missing-icons-latest-tracks-121-appliance
- The proposed workaround worked for me with a minor tweak (added RAILS_ENV=production , as suggested on the Tracks GitHub page : github.com/TracksApp/tracks/blob/v2.3.0/doc/installation.md:
bundle exec rake assets:precompile RAILS_ENV=production
- You need to run this in Linux command line (or SSH) on the VM.
- Then, after restarting my virtual machine, I have got the icons after login into Tracks.
- Hope this helps, in case other students will face a similar issue.