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 commented 2 weeks ago

@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 commented 2 weeks ago

@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.

kartoza / miniSASS