You can run the application locally or run it from a cloud system.
The application has been deployed to Heroku at
The cloud version will:
/sessionid
is called with 2 minutes of inactivityBy default all requests use the 'global' set of data. This makes the application easy to use for single users and multiple users can access this, although they will be amending each others data.
If a user wants a unique session, perhaps because they want to automate and have deterministic results without interference from other users they must use a X-SESSIONID
header.
GET /sessionid
e.g. GET http://localhost:44306/listicator/listicator/sessionid
download the jar from TestingApp Releases on Github
java -jar <insertnameofjarfilehere>.jar
rest-list-system.jar
then it would be java -jar rest-list-system.jar
If you double click it then it will be running in the background on port 4567 - you might have to use task manager to kill the Java VM that it is running on to exit.
Three users are created by default with different permissions: superadmin
, admin
, user
- all have the default password set to password
Use Basic authentication to use these users.
superadmin
, password: password
admin
, password: password
user
, password: password
-port=1234
set the port to supplied integer (defaults to 4567)-bugfixes=false
(defaults to true)-resettimmer=MILLISECONDS
e.g. -resettimmer=1000
RestListicatorApiResetMillis
-maxsessionseconds=SECONDS
e.g. -maxsessionseconds=60
/sessionid
to be deleted after 60 seconds of inactivityRestListicatorMaxSessionSeconds
/heartbeat
- is the server alive?/lists
- manage the List entities - create, amend lists/lists/{guid}
- create, amend, delete a List/users
- user management - create, delete/users/{username}/password
- amend a User's password/users/{username}/apikey
- amend a User's api key/feature-toggles
- superadmin
can toggle app features on and off/sessionid
- get a unique sessionid to isolate your testing from other users, use the session id in a X-SESSIONID
headerNOTE:
if you see{username}
or{guid}
mentioned in the end point documentation.
This means "replace {username} with an actual username"
e.g./users/{username}/apikey
would be/users/admin/apikey
The end points may be nested in a sub path e.g. /listicator/heartbeat
Check with your system admin to find out how the application has been configured.
On heroku the requests are of the form:
GET https://rest-list-system.herokuapp.com/listicator/heartbeat
Running locally it is likely to be (by default):
GET https://localhost:44306/listicator/heartbeat
/heartbeat
GET
- return 200 to indicate server is runninge.g.
curl -i -X GET http://localhost:44306/listicator/heartbeat
curl -v -X GET http://localhost:44306/listicator/heartbeat
/lists
GET
POST
{title:'my title'}
PUT
title
, description
, guid
, createdDate
, amendedDate
Note: continuation character on mac is \
and on Windows it is ^
curl -X GET ^
http://localhost:44306/listicator/lists ^
-H "accept: application/json"
'GET /lists'
Accept: application/json
{
"lists": [
{
"guid": "d4625287-989a-4454-b01a-cb99545a87a6",
"title": "title",
"description": "",
"createdDate": "2017-07-19-15-53-14",
"amendedDate": "2017-07-19-15-53-14"
}
]
}
curl -X GET ^
http://localhost:44306/listicator/lists ^
-H "accept: application/xml"
Accept: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<lists>
<list>
<guid>d4625287-989a-4454-b01a-cb99545a87a6</guid>
<title>title</title>
<description></description>
<createdDate>2017-07-19-15-53-14</createdDate>
<amendedDate>2017-07-19-15-53-14</amendedDate>
</list>
</lists>
GET
- return the details of a particular list
?title=exactTitle
?title="partialTitle"
PUT
- amend a list or create a new list when supplied with full details of the listPOST
- amend details of a list
PATCH
- partial amend of a list
DELETE
- delete a list
GET
- return the details of a particular list but without the fields in the comma separated fieldlist
e.g. guid,title
curl -X GET \
http://localhost:44306/listicator/lists/d4625287-989a-4454-b01a-cb99545a87a6 \
-H 'accept: application/json'
GET /lists/{guid}
Accept: application/json
{
"guid": "d4625287-989a-4454-b01a-cb99545a87a6",
"title": "title",
"description": "",
"createdDate": "2017-07-19-15-53-14",
"amendedDate": "2017-07-19-15-53-14"
}
curl -X GET ^
http://localhost:44306/listicator/lists/d4625287-989a-4454-b01a-cb99545a87a6 ^
-H 'accept: application/xml'
Accept: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<list>
<guid>d4625287-989a-4454-b01a-cb99545a87a6</guid>
<title>title</title>
<description></description>
<createdDate>2017-07-19-15-53-14</createdDate>
<amendedDate>2017-07-19-15-53-14</amendedDate>
</list>
POST /lists
With a body
{title:'my title custom'}
Would create a list - try experimenting with the different fields: guid
, description
, createdDate
, amendedDate
etc.
PATCH /lists/{guid}
Where {guid}
would be an actual guid value e.g. d4625287-989a-4454-b01a-cb99545a87a6
{
"guid": "d4625287-989a-4454-b01a-cb99545a87a6",
"title": "title2",
}
_currently does not comply with https://tools.ietf.org/html/rfc7396 _
/users
GET
- return usernames of all users
?username=exactmatch
e.g. ?username=admin
?username="partialmatch"
e.g. ?username="adm"
curl -X GET http://localhost:44306/listicator/users
/users
POST
- creat a user with username
and password
curl -X POST \
http://localhost:44306/listicator/users \
-H 'accept: application/json' \
-H 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
-H 'content-type: application/json' \
-d '{username:"username", password:"password"}'
/users/{username}
GET
- return details of a user
curl -X GET http://localhost:44306/listicator/users/superadmin ^
-H "authorization: Basic YWRtaW46cGFzc3dvcmQ="
/users/{username}/password
PUT
- set the password
PUT /users/{username}/password
XML:
<user><password>newPassword</password></user>
JSON:
{password:'newPassword'}
/users/{username}/apikey
PUT
- set the API AuthKey
PUT /users/{username}/apikey
XML:
<user><apikey>newApiKeyIsThisYes</apikey></user>
JSON:
{apikey:'newApiKeyIsThisYes'}
/feature-toggles
GET
- return status of all feature toggles
POST
- amend a list of feature toggles
Content-Type
Content-Type
header to specify the format of the payload as either XML or JSONapplication/json
means the payload is represented as JSONapplication/xml
means the payload is represented as XML400
error will be returned if the payload can not be converted into the appropriate representationContent-Type
is supplied then the application assumes a JSON representation.Accept
Accept
header to specify the format of the desired responseapplication/json
means you want to receive JSONapplication/xml
means you want to receive XMLAuthentication
header with the value Basic
followed by the username:password
base 64 encodedX-API-AUTH
with a value of the api key
defined for each user. the api key
is visible to the user when they make a GET
request for their user detailsX-HTTP-Method-Override
header to allow clients that don't support verbs such as PATCH
OPTIONS
can be used on all endpoints to receive the Allow
header with the allowed verbs.404
is returned if the end point is not recognised405
is returned if a method which is not mentioned in Allow
is used on an an endpoint500
is returned in the event of an unhandled condition in the server - this should never occurThe system has been coded with some known bugs - these are all fixed by default. If you would like to test your testing skills then start with -bugfixes=false
to have the known bugs present in the application.
See if you can find them.
java -jar rest-list-system.jar -bugfixes=false
This application has been written by Alan Richardson
Copyright Compendium Developments Ltd
Source code is available as part of "The Evil Tester's Compendium of Testing Apps" with source on Github.
Deployed to Heroku at rest-list-system.herokuapp.com/listicator/
Recommended tools for exploratory testing of REST API:
If you are interested in learning how to test APIs then you might find the book by Alan Richardson called "Automating and Testing a REST API" useful.
The book has a support page with many videos and sample code.