Testing API endpoints

Api endpoints return only json objects and can be easily debugged using API testing tools like Insomnia. Insomnia is an open source API testing tool like Postman.

Configuring Insomnia for API testing

Dark mode

To preserve our sanity we can go to settings and select dark theme. This should be the first this you ever do.

SSL validation

Docker image is creating it's own signed certificate and thus it cannot be validated. So we need to disable it in the settings.

1. Click on settings
2. Scroll down to Security
3. Uncheck "Validate certificates during authentication"

Testing API endpoints

Testing enrollment

1. Open Insomnia and click on "new Collection"
2. Assuming we want to test enrollment through API. Click on "New request" and set the type to be POST.
3. Set the endpoint to be https://127.0.0.1/api/enrollment
4. Select body type to be form.
5. Paste in following content inside body. This is what API expects on this endpoint.

Warning: Make sure that all urls are prepended with https://. .htaccess rule redirects any http connection to https and in the process fucks up request body and converts POST requests into a GET request for some reason.

key	value
name	jack Sparrow
isMale	1
licensee
phone	123456789
birthDate	1994-10-10
zip	7011
address	Munkegata 68B
email	[email protected]

6. Click send

You should get a response like this:

{
	"dryrun": false,
	"name": "Jack Sparrow",
	"isMale": true,
	"phone": "+47123456789",
	"birthDate": "1994-10-10",
	"zip": 7011,
	"address": "Munkegata 68B",
	"email": "[email protected]",
	"licensee": "",
	"error": false,
	"message": "Member has been registered successfully",
	"age": 27,
	"first_name": "Jack",
	"surname": "Sparrow",
	"user_exists": false,
	"approved_date": null,
	"membership_status": "pending",
	"CIN_hash": "5a97d0ed6233fae36d8990042ece639ee27a11a9b319a6377d3d4419a44ad993",
	"CIN": 0,
	"url": "https:\/\/127.0.0.1\/store?product_hash=31e61c8253b54cdde3b9"
}

As you can see the server has successfully parsed the first name and surname, appended +47 to the phone number. You can also specify dryrun=1 in the request and changes will not modify anything on the server.

You can now test the designed functionality. Here are some examples:

• Name contains multiple spaces will get trimmed automatically
• Enrollment with the same phone number (duplicate entry)
• A user is very old
• email is not an email

Testing other endpoints

Writing documentation for every single endpoint takes a long time. Especially when they are subject to change. Just read through the source code and use this as a tool for testing it. In future some automated testing / fuzzing would be a nice feature to have.

General API structure

All apis has (or should have) roughly this structure:

if (!validate_rule_1(input)) {
    return "Client Error";
}
if (!validate_rule_2(input)) {
    return "Client Error";
}

...

if (!dryrun){
    destructive_action(input);
}
return "Success";

All validation rules are simple if statements and final destructive action should be at the bottom with the return value.

Testing secured endpoints

Some endpoints have authentication:

// require log in
if (!Authenticator::is_logged_in()) {
	log::forbidden("Access denied", __FILE__, __LINE__);
}

// check permissions
if (!$access_control->can_access("api", "isMember")) {
	log::message("Info: Access denied for " . Authenticator::get_username(), __FILE__, __LINE__);
	log::forbidden("Access denied", __FILE__, __LINE__);
}

Authentication validation is done through cookies. Specifically PHPSESSID.

Create a new GET request to https://127.0.0.1/api/memberlist. This endpoint is secured because it literally dumps all active members. When clicking send you should get Access denied error. Good.

Obtaining a session cookie for authentication

Assuming you're using a chromium based browser:

1. Navigate to https:127.0.0.1/admin
2. Log in
3. Click Ctrl + Shift + J
4. Select tab Storage
5. Click on Cookies and then "https://127.0.0.1"
6. Scroll until you find cookie with the name PHPSESSID and copy it.

Applying cookie in Insomnia

1. If you've not sent a GET request to the API endpoint yet do it now. It will set all cookies and it will be easier to replace the one that is not correct.
2. Click on cookies on the left hand side.
3. You should see a line with the domain "127.0.0.1". Click edit
4. Find key with name PHPSESSID and replace it with the value from steps above.
5. Try sending the request again.
6. If this didn't work make sure you're logged in the web browser by going to https://127.0.0.1/admin

Testing

Each json file can be validated using a json schema file. A json schema is a json file describing how a json file should be structured like. Take a look at this video. To create random fake user data faker.js can be used.