APIs

[docuracy]

Current 'Spectacular' Swagger URLs:

• http://localhost:8001/api/docs/
• ~http://localhost:8001/api/schema/redoc/~

settings.py now has a SWAGGER_SETTINGS variable, which might be employed using the settings listed at https://django-rest-swagger.readthedocs.io/en/latest/settings/

• [x] Configure Swagger
• [ ] Ensure that each referenced API class begins with an appropriate docstring.
• [ ] Best practice API namespaces/URIs /DOIs
• [ ] Inventory existing external API endpoints, provide developer access to explore them
• [ ] swagger page displaying our existing public endpoints; test all work
• [ ] also endpoints under remote/ (earlier Recogito experiment); confirm secure for writes
• [x] add link to this new swagger dev api page anywhere on existing api page (kg will edit page later)

[docuracy]

This is proving to be far more time-consuming than anticipated. I began with the SpatialAPIView as it is one I am familiar with, but configuring it to properly document the various inputs and outputs using the @extend_schema decorator is not at all straightforward. It's a whole new language, with which 🤖 is none-too-familiar, it seems - much hallucination.

In order to get things only nearly right I've had to largely rewrite the View, and make some changes to the LPFSerializer too. At least that now returns feature geometries in full as a GeometryCollection, together with all the various LPF extension properties.

As for the remote APIs, the way they are set up (with DefaultRouter) the API Documentation offers GET, POST, PUT, PATCH, and DELETE URLs for every method, ~and I'll need some guidance as to which are intended to be used~ [EDIT: I've fixed the URLs and drafted the documentation]. They do appear to be fully protected with TokenAuthentication for every method, so cannot be used at all without authentication.

The standard API exposes the following GET URLs at present. @kgeographer: When you have a moment, would you please tick those which you think should remain open? I'll then document those and hide the others.

• [ ] /api/area/{id}/
• [ ] /api/area_features/
• [ ] /api/datasets/
• [ ] /api/db/
• [ ] /api/gallery/{type}/
• [ ] /api/geojson/
• [ ] /api/geoms/
• [ ] /api/place/{dslabel}/{src_id}/
• [ ] /api/place/{id}/
• [ ] /api/place_compare/{id}/
• [ ] /api/placetable/
• [ ] /api/placetable_coll/
• [ ] /api/schema/
• [ ] /api/spatial/
• [ ] /api/user/{id}/
• [ ] /api/user_area_features/
• [ ] /api/users/

[kgeographer]

This issue is not "beta must" - however #184, assigned to me, is.

Getting the exiting API into the swagger page, etc. is still highly desirable but not critical for 1 June. #184 is where I fix existing code for what is on the usingapi.html page so they at least return something. some are broken.

Any thing that is far more time-consuming and not beta must has to be shelved!