[CWM] Create Swagger spec for MykoMap API

[ms0ur1s]

Description

Based on the API design for MykoMap discussed in Issue DigitalCommons/mykomap#267 and the notes from the meeting on 20/8, create a Swagger (OpenAPI) specification. This spec will outline the API endpoints, request/response formats, and any necessary validation rules.

Objectives

• Define the API endpoints as outlined in the meeting notes.
• Specify the HTTP methods (GET, POST, DELETE, etc.) for each endpoint.
• Include request and response schemas, including data models.
• Document error handling and expected status codes.

Acceptance Criteria

• A complete Swagger spec that covers all discussed API endpoints.
• The spec should be validated and ready for use by the development team.
• Ensure the spec is reviewed and approved by at least one senior developer.

[rogup]

@wu-lee has created a draft API spec here: https://app.swaggerhub.com/apis/SWAGGERHUBWULEE/mykomap/0.1.0

At the moment the dataset is an array of Locations, with no ID, we probably need to investigate the feasibility if including IDs and names

Nick suspects we might be able to keep the data file sizes smaller if we supply Locations only in the initial data, use an item index number in the API instead of the id, and load the names only on request. But we can also try with and without names, and IDs.

My personal preference would be try with IDs and lng/lats since this is simplest and probably less bug-prone, when we start adding/removing initiatives from the datasets. And stripping ids will only have a linear affect on time. If it's taking too long to load and we need to drastically reduce this so that the app is usable for people in the world with slow internet connections, we'll need to make a bigger change e.g. using vector tiles on initial load, which has already been demo'ed.

[lin-d-hop]

After a chat on 29/8 the updated spec that will be implemented is:

1) Search by search term and/or prop filters (search query parameters -> array of indexes) N * category IDs + (optional) text fragment -> list of indexes http://blah/api/search/categories=A,B,C/text=D

2) Search by search term and/or prop filters (search query parameters + fields to return -> paginated array of objects)

3) Retrieve popup contents (index -> Html) http://blah/api/item/[index]

4) Retrieve full set of lng/lats ( _ -> JSON array)

[wu-lee]

I suggest we want to add some information about the API on the default route, or perhaps under about/. This so we know what version / commit we're looking at when we're testing it.

• [http://blah/api/about]() -> {name: 'Mykomap API', apiVersion: 'v4.0.0-4-0fdeaf', deployed:'2024-09-02T14:56:04'} (version is generated using something like git describe --always --tags --dirty --abbrev=6)

[wu-lee]

@wu-lee has created a draft API spec here: https://app.swaggerhub.com/apis/SWAGGERHUBWULEE/mykomap/0.1.0

Note this has moved to a DCC account here:

https://app.swaggerhub.com/apis/DigitalCommonsCoop/Mykomap/0.1.0

(Details in BitWarden)