miniSASS API tests

[EliVolsch]

@amyburness

miniSASS API Test

Date	07 Oct 2024
Tester	Eli
Documentation	Link
Test System Specifications
Test Description	Follow the walkthrough of the miniSASS API documentation and replicate the steps laid out to try and replicate the actions. The documentation features ways to access and retrieve information from Postman, Swagger, and Redoc.

Result Key

🟢 = Pass / Output as expected
🟡 = Output received but not what was expected / Process failed one or more times before pass
🔴 = Fail / Could not process
⚠️ = Error / Crash

All images in the table below can be clicked on to get an enlarged view of the image

Tests Results

No	Description	Status	Notes
1	Postman	🟢
	Download and install Postman as per instructions in the documentation	🟢
	Run GET request with date parameter https://minisass.org/monitor/sites-with-observations/?start_date=2024-04-13		Output 200 OK
	Request without specific date	🟢
	Run GET request without a specific date https://minisass.org/monitor/sites-with-observations	Output 200 OK
	View Image from results	🟢
	View metadata from GET request https://minisass.org/monitor/sites-with-observations/?start_date=2024-04-13
	Select different formats	🟢
	Select a different format from the response.
2	Swagger	🔴⚠️
	Navigate to Swagger https://minisass.org.com/swagger/.		Unable to navigate to URL.
3	Redoc	🔴⚠️
	Navigate to Redoc https://minisass.org.com/redoc/#tag/monitor/operation/monitor_site-observations_read		Unable to navigate to URL.

[EliVolsch]

@amyburness @tinashechiraya

miniSASS API Re-test Swagger & Redoc

Date	08 Oct 2024
Tester	Eli
Documentation	Link
Test System Specifications
Test Description	Re-test the API walkthrough from the documentation. Previous tests for Swagger and Redoc failed due to the links in the documentation being incorrect. A separate ticket has been opened for updating the documentation. Updated links: Swagger: https://minisass.org/swagger/ Redoc: https://minisass.org/redoc/

Test Results

No	Description	Status	Notes
2	Swagger	🟢
	Navigate to Swagger	🟢
	Navigate to Swagger URL https://minisass.org/swagger/
	GET request	🟢
	Navigate to GET /monitor/sites-with-observations/ Tryout and execute a query with parameter start_date as 2024-04-02. Receive output Code 200
	Download	🟢
	Download data in JSON format. View images from the JSON output by following image URLs
3	Redoc	🟢
	Navigate to Redoc	🟢
	Navigate to Redoc URL https://minisass.org/redoc/
	GET request	🟢
	Navigate to and view sites with observations URL https://minisass.org/redoc/#tag/Sites-with-Observations		Not sure if there are any outputs to get from here, the documentation does not specify any further actions. Redoc does, however, provide a detailed explanation of what each part of the API does and how it functions.

[EliVolsch]

@ketankartoza

Notes for improvement of documentation

I found that the API documentation section seemed a little repetitive and hard to read. Apart from the URLs that need to be updated, many of the images in the documentation were hard to see (small hard-to-read text) and the only way to effectively view the image was to right-click and select "open in a new tab." The following recommendations are offered to improve the documentation:

1. Update and test the URLs provided in the documentation. Make them links instead of text so when the user reads "click on the URL" they can simply take that action, and don't need to copy and paste the URL in their browser.

2. Make clear distinctions between explaining the interface and the next steps to be taken in the walkthrough. This section reads difficult and makes the user feel like they are taking steps and then basically repeating the steps again. I believe a clear screenshot of the various sections of the interface along with an explanation of what that specific section is, followed by a "How to use ..." section would have positive results on the readability of this section.

3. Provide clearer screenshots. In most cases, users might have smaller screens or simply the manner in which the documentation is displayed might cause the image to become hard to see/understand. I believe taking screenshots on smaller screen sizes or alternatively having the image as a clickable link to enlarge it would greatly benefit the documentation. As an example, to make the image a clickable link, the following format can be applied:
[![image]({link-to-image}]({link-to-image}).
This is the way I set up all the images in this report to allow the reader to easily view a larger image when required.