Skip to content

Commit d3719ad

Browse files
eviltestereviltester
committed
added some apps to the expanded pages
1 parent 425bb79 commit d3719ad

File tree

6 files changed

+442
-16
lines changed

6 files changed

+442
-16
lines changed

‎challenger/src/main/resources/content/changes.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: API Challenges Change Log
3+
description: Change log for the API Challenges
4+
showads: true
5+
---
6+
7+
# Change Log
8+
9+
## 2025/02/16 - added pages for apps: Tracks, Best Buy, FX Trade Hub
10+
11+
- Added page for [Best Buy API Playground](/practice-sites/apps/bestbuy) showing how to run, and sample exercises to get started. The Best BUY API Playground is a full CRUD API with Open API documentation and a Swagger UI. The application also has a lot of data available when it starts.
12+
- Added page for [FX Trade Hub](/practice-sites/apps/fxtradehub) showing how to run, and sample exercises to get started. The FX Trade Hub is a simple API with a Swagger UI. Has a lot of default data installed and is suitable for full CRUD operation testing.
13+
- Added page for [tracks](/practice-sites/apps/tracks) showing how to run, and sample exercises to get started. Tracks offers a Web App UI and a REST API and was the case study application used in my book [Automatinc and Testing a REST API](https://www.eviltester.com/page/books/automating-testing-api-casestudy/)
14+
- Removed [TODO API Sample](https://github.com/g33klady/TodoApiSample) from list of practice apps because during testing in docker the api failed to work

‎challenger/src/main/resources/content/practice-sites.md‎

Lines changed: 30 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -257,27 +257,43 @@ To have the most control over your practice testing session you can download an
257257

258258
Getting started with these applications can be a little harder than using the online versions and may require installing Java, Node or Docker.
259259

260+
### Best Buy API Playground
261+
262+
- Best Buy API Playground is a full API that can be run locally using Node or Docker
263+
- Full range of CRUD operations is supported using `GET`, `POST`, `PATCH`, `DELETE`
264+
- Large set of data is provided
265+
- Swagger UI is available
266+
- Open API Definition is downloadable
267+
268+
[Read a full overview of Best BUY API Playground with sample exercises](/practice-sites/apps/bestbuy)
269+
270+
### Tracks
271+
272+
- Tracks is a full todo app that can be run locally if you have Ruby on Rails installed, or use a [virtual machine from Turnkey](https://www.turnkeylinux.org/tracks) or [run from docker](https://github.com/eviltester/tracksdocker).
273+
- I recommend running it from Docker
274+
- Tracks is the case study application used in the book [Automating and Testing a REST API](https://www.eviltester.com/page/books/automating-testing-api-casestudy/)
275+
276+
[Read a full overview of Tracks with sample exercises](/practice-sites/apps/tracks)
277+
278+
### FX Trade Hub
279+
280+
- FX-TradeHub is a simple API simulating a trading application.
281+
- Can be run locally if you have Node installed or from a Docker file.
282+
- Has a Swagger UI for easy exploration
283+
284+
[Read a full overview of Fx Trade Hub with sample exercises](/practice-sites/apps/fxtradehub)
285+
286+
### More Applications
287+
260288
I've listed a few applications here initially and will expand the instructions to include walkthroughs and setup guides in future updates.
261289

262290
- [Api Challenges](https://github.com/eviltester/thingifier/tree/master/challenger)
263-
- API challenges can be run locally if you install a Java SDK and maven as pre-requisites.
264-
- [BestBuy API Playground](https://github.com/BestBuy/api-playground)
265-
- The BestBuy API Playground can be run locally if you have Node and npm installed.
291+
- API challenges can be run locally if you install a Java SDK and maven as pre-requisites.
266292
- [Device Registry Service](https://github.com/AutomationPanda/device-registry-flask)
267293
- The Device Registry Service can be run locally if you have Python 3 and Pip installed.
268-
- [Tracks](https://www.getontracks.org/)
269-
- Tracks is a full todo app that can be run locally if you have Ruby on Rails installed, or use a [virtual machine from Turnkey](https://www.turnkeylinux.org/tracks) or [run from docker](https://hub.docker.com/r/staannoe/tracks/).
270-
- I recommend running it from Docker
271-
- [Instructions and Video Tutorial for using Tracks in Docker or a Virtual Machine](https://www.eviltester.com/page/books/automating-testing-api-casestudy-support/#dockervideo)
272-
- [TODO API Sample](https://github.com/g33klady/TodoApiSample)
273-
- This is the support app for [Hilary Weaver](https://g33klady.com/)'s Testing API Tutorial.
274-
- Has instructions to use from docker
275294
- [JSON Server](https://github.com/typicode/json-server)
276295
- Can be run locally if you have Node and npm installed.
277-
- [FX-TradeHub](https://github.com/sd576/FX-TradeHub-API/tree/main)
278-
- Can be run locally if you have Node installed.
279-
- I created a Docker file which can run the application if you use Docker [here](https://github.com/eviltester/thingifier/tree/master/docker)
280-
- Has an OpenAPI spec to use within a Swagger UI or REST Client
296+
281297

282298
<!--
283299

‎challenger/src/main/resources/content/practice-sites/apps/bestbuy.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: Best Buy API Playground - An old version of the Best Buy API - Practice API
3+
description: Bes tBuy API Playground is an old version of the Best Buy API. Notable for comprehensive query filter operations.
4+
showads: true
5+
---
6+
7+
In addition to our [API Challenges](/gui/challenges) you should practice on as many sites as possible. Try [BestBuy API Playground](https://github.com/BestBuy/api-playground).
8+
9+
# Best Buy API Playground - A Practice GET API
10+
11+
The Best Buy API Playground is a node application which implements an older version of the Best Buy API. It comes pre-populated with production-like data.
12+
13+
Since this is a practice version of the API, update and delete operations are enabled in addition to the expected `GET` verbs. These would not be available in the production version of the API.
14+
15+
Summary:
16+
17+
- Best Buy API Playground is a full API that can be run locally using Node or Docker
18+
- Full range of CRUD operations is supported using `GET`, `POST`, `PATCH`, `DELETE`
19+
- Large set of data is provided
20+
- Swagger UI is available
21+
- Open API Definition is downloadable
22+
23+
## Running The Application Using Node
24+
25+
If you have node installed then the API can best started by cloning the repository and using `npm`.
26+
27+
Full instructions are on the [GitHub page](https://github.com/BestBuy/api-playground), copied here for ease of reference:
28+
29+
```
30+
git clone https://github.com/bestbuy/api-playground/
31+
cd api-playground
32+
npm install
33+
npm start
34+
```
35+
36+
The Best Buy API Playground will now be accessible on `http://localhost:3030`
37+
38+
I personally prefer to run the application using Docker as described below.
39+
40+
## Running The Application Using Docker
41+
42+
Create the Docker image locally:
43+
44+
```
45+
git clone https://github.com/BestBuy/api-playground
46+
cd api-playground
47+
docker build --tag bestbuy .
48+
```
49+
50+
Then run the Docker image, making sure you map the exposed port `3030`:
51+
52+
```
53+
docker run -d --name=bestbuy-api-playground -p 3030:3030 "bestbuy"
54+
```
55+
56+
I map the port to `3030` on localhost to make the Swagger documentation URL work with the default values.
57+
58+
## Documentation End Points
59+
60+
You can then access:
61+
62+
- the basic api documentation at
63+
- `http://localhost:3030`
64+
- A Swagger UI Front End at
65+
- `http://localhost:3030/docs/`
66+
- A Swagger API Definition file at
67+
- `http://localhost:3030/swagger.json`
68+
- A PostMan collection has been bundled with the app at
69+
- `http://localhost:3030/postman/API.postman_collection.json`
70+
- The Queries documentation shows some examples of queries to use on the API. This is useful because the GET API supports a complex set of query filters using SQL-like operators.
71+
- `http://localhost:3030/queries`
72+
73+
## API Endpoints
74+
75+
The application is bundled with sample data so you will be able to query the data on the back end immediately.
76+
77+
The main endpoints are:
78+
79+
- `/products` - products available in the database.
80+
- `/categories` - product categories and their subcategories/path.
81+
- `/stores` - returns a list of Best Buy store locations.
82+
- `/services` - returns a list of services available at Best Buy stores.
83+
- `/version` - returns the current version of the application.
84+
- `/healthcheck` - returns information about the application's health.
85+
86+
87+
## Exercises
88+
89+
### Exercise - `GET` all the main endpoints
90+
91+
- Issue a GET request on each of the top level endpoints listed above
92+
- Initially do this using the Swagger UI `http://localhost:3030/docs/`
93+
- Repeat the exercise using a REST API Client to gain more control. You can download the Swagger file to pre-populate the requests in your REST Client.
94+
95+
### Exercise - Explore the Example Query Formats
96+
97+
- Use the list of Query formats on the Query Example page
98+
- `http://localhost:3030/queries`
99+
- Initially do this by clicking on the links
100+
- Copy the URLs into your REST client and repeat the exercise
101+
- Amend Query parameters to explore the results
102+
103+
### Exercise - Create and Update the Data
104+
105+
- Explore the endpoints to create and amend the data in the backend
106+
- Use `OPTIONS` do check if the endpoints honour the verbs listed
107+
108+
### Exercise - Does the API only support JSON?
109+
110+
- The response format can sometimes be influenced using the `accept` header to tell the server that the client will accept a different format for the response.
111+
- By default the server responds with `JSON`.
112+
- What happens if you ask the server for `application/xml`?
113+
- What other formats could you ask for?
114+
115+
## Some Observations
116+
117+
### Create and Updating Data
118+
119+
- When creating data I noticed that the system was fussy around headers, but in a misleading way. Sending through a valid payload in 'text/plain' format I received the information that it `should have required property 'name'` rather than content-type not accepted.
120+
- The server checks payloads for extra and unexpected fields.
121+
- Server responds with all validations that the request fails, not just the first one, which is useful for debugging requests.
122+
- Duplicate fields are allowed with the last one being accepted
123+
- JSON validation fails with a `500` error rather than a `400` error suggesting that a general exception is thrown but not trapped to return a `400` (client) error. NOTE: the swagger documentation suggests that a `400` will be returned
124+
- The swagger documentation did not show the field validation rules so I experimented to find validation lengths. And then used an online counterstring tool to check the length calculations [counterstring generator](https://eviltester.github.io/TestingApp/apps/counterstrings/counterstrings.html)
125+
- Service names do not need to be unique
126+
- Trying to amend an existing item using `POST` returned a `404` rather than a `405 Method Not Allowed`, which also contradicts the methods listed when I asked for `OPTIONS`
127+
128+
### `accept` Header
129+
130+
- The API examples are all `JSON` so I tried asking the API for `application/xml` I received a `500` error. I rather expected a `400` error because the request was asking for something the API did not support, rather than the server throwing a `500` General Error.
131+
- Since the `xml` request failed I wondered what would happen with a `text/html` response and I found it interesting that the server did actually respond with an error in HTML format.

‎challenger/src/main/resources/content/practice-sites/apps/fxtradehub.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: FX Trade Hun - A Productivity GTD App - Practice Web App and API
3+
description: Tracks is a mature application implementing the Getting Things Done productivity method with a Web GUI and API.
4+
showads: true
5+
---
6+
7+
In addition to our [API Challenges](/gui/challenges) you should practice on as many sites as possible. Try [FX-TradeHub](https://github.com/sd576/FX-TradeHub-API).
8+
9+
# FX Trade Hub - A Web Application with API
10+
11+
[FX-TradeHub](https://github.com/sd576/FX-TradeHub-API) is an API to simulate a trading system. It is written for Node and can be run locally if you have node installed. To make it easy to run, we have also created a Docker file that makes it easy to get started.
12+
13+
The API has a Swagger UI.
14+
15+
Summary:
16+
17+
- [FX-TradeHub](https://github.com/sd576/FX-TradeHub-API)
18+
- Can be run locally if you have Node installed.
19+
- I created a Docker file which can run the application if you use Docker [here](https://github.com/eviltester/thingifier/tree/master/docker)
20+
- Has a Swagger UI to allow easy exploration of the API
21+
22+
23+
## Running The Application
24+
25+
### Using Node
26+
27+
Instructions for running the application are available in the project readme.
28+
29+
- [github.com/sd576/FX-TradeHub-API](https://github.com/sd576/FX-TradeHub-API)
30+
31+
32+
### Using Docker && cURL
33+
34+
Create the Docker image locally by downloading our Dockerfile for the project or cloning the apichallenges github repo.
35+
36+
#### Download just the Docker file
37+
38+
Create the Docker image locally by downloading our Dockerfile for the project:
39+
40+
```
41+
mkdir fxtradehub
42+
cd fxtradehub
43+
curl https://raw.githubusercontent.com/eviltester/thingifier/refs/heads/master/docker/fxtradehub/Dockerfile -o Dockerfile
44+
docker build --tag fxtradehub .
45+
```
46+
47+
Then you can run the image:
48+
49+
```
50+
docker run -it --name=fxtradehub -p 3000:3000 fxtradehub
51+
```
52+
53+
And visit `http://localhost:3000/api-docs` to see the Swagger Docs UI.
54+
55+
#### Cloning the API Challenges repo
56+
57+
Create the Docker image locally by downloading our Dockerfile for the project:
58+
59+
```
60+
git clone https://github.com/eviltester/thingifier
61+
cd thingifier
62+
docker build -t fxtradehub -f ./docker/fxtradehub/Dockerfile .
63+
```
64+
65+
Then you can run the image:
66+
67+
```
68+
docker run -it --name=fxtradehub -p 3000:3000 fxtradehub
69+
```
70+
71+
And visit `http://localhost:3000/api-docs` to see the Swagger Docs UI.
72+
73+
74+
## API Endpoints
75+
76+
The API is a CRUD interface using verbs: `GET`, `POST`, `PUT`, `DELETE`.
77+
78+
The top level url path for the api is `/api`.
79+
80+
Then sub paths for the endpoints:
81+
82+
- `/counterparties`
83+
- `/counterparties/{id}`
84+
- `/settlements`
85+
- `/settlements/{counterpartyId}`
86+
- `/settlements/{counterpartyId}/{currency}`
87+
- `/trades`
88+
- `/trades/{id}`
89+
90+
91+
eg. `GET http://localhost:3000/api/counterparties`
92+
93+
It is a fun API to test. It is still in its early stages, and as it is a hobby project test API... expect to be able to find bugs.
94+
95+
## Exercises
96+
97+
A set of suggested exercises to explore the API.
98+
99+
### Exercise - Use the Swagger UI to Explore the Data
100+
101+
- The Swagger UI `http://localhost:3000/api-docs` will allow you to issue the accepted requests for the API
102+
- Use the Swagger UI to issue `GET` requests and explore the data
103+
- Use the Swagger UI to amend the data in the system.
104+
- Read the Swagger UI documentation carefully and see if you spot any issues
105+
106+
### Exercise - Use a REST Client to Explore the API
107+
108+
- Having gained familiarity with the normal usage of the API, use a REST client to explore the API in more depth.
109+
- When calling `OPTIONS` does the endpoint honour all the verbs listed?
110+
111+
112+
### Exercise - Explore the Validation
113+
114+
- The API documentation does not describe all the validation rules, try and trigger validation errors.
115+
- Vary the input data to see which fields have domain validation rules and which do not e.g. does an email have to be an email?
116+
- Identify which fields need to be present and which are optional.
117+
- Are you happy with all the field validations?
118+
119+
### Exercise - Explore Amending Values
120+
121+
- Use the `PUT` verb to amend existing entities
122+
- When an amend payload using `PUT` is accepted, does it always amend the entity correctly?
123+
- Any fields that you identified as optional during creation. Can you amend an existing entity with those values to make the field value optional?
124+
125+
126+
## Some Observations
127+
128+
These endpoints were made at a specific point in time. The system may have changed since, and you might not be able to repeat the observations below. They are provided here to give you some insight into the type of testing I performed.
129+
130+
### Swagger UI
131+
132+
- When reviewing the Swagger documentation I spotted some inconsistencies in the status code descriptions with the endpoint e.g. `/counterparties` would never return a `404` for a missing counterparty even though this is suggested by the documentation.
133+
134+
### Exploring the API
135+
136+
- I found it interesting that the ID 'looks like' it should be an integer `1` but is actually a string `001` and I had to use the full `001` to access specific items.
137+
- Creating data was interesting. When experimenting with APIs I tend to `GET` and then use the payload in a `POST` to try and create data. But in this instance when creating a counterparty the phone number would not validate as the returned number `+44 20 7116 1000` exceeded the maximum length of 15.
138+
- I like to call endpoints with verbs which are not listed as valid to see the response. Ideally I'll see `405 Method not allowed` rather than a `404`
139+
140+
### Exploring the Validation
141+
142+
- I tend to check for handling of invalid request formats, not just field formats. Ideally I expect to see a message about malformed JSON with a `400` response as `500` errors can be harder to diagnose.
143+
- Some fields validate as requiring a value and it is not possible to amend them to be `null`, although it is possible to create them as `null`.
144+
- The validation on the primary key allowed me to create an empty or null id, and then subsequently would not be able to amend or delete this entity.
145+
- I like to create entities with minimum payloads to see if the system tells me what should exist, the error report for invalid counterparty items with not enough fields seems to be "Counterparty with this ID already exists"
146+
147+
### Exploring the Amendment
148+
149+
- When amending I like to check if I can amend fields to be `null`, particularly with a `PUT` as I view a `PUT` as overwriting and not a partial update. For this API implementation `PUT` is treated as a partial update and if a field is missing it is not updated on the backend.

0 commit comments

Comments
 (0)