Use the OpenAPI specification

[arthur-shaw]

Objective 🎯

• Know endpoints available (list of named objects in "paths" object)
• Know which endpoints are deprecated ("deprecated": true)
• Have details of what to expect from each API endpoint (with an eye to creating archetypes of the return object and checking the actual return against expectations)

User stories 📇

The "user" here is not an end user but the developer and the package's functions.

• Get OpenAPI schema from a server from {base_url}/swagger/v1/swagger.json
• Create a function to check whether all exported functions will work for a target server, providing an informative message listing those that don't
• Check whether a specific expected endpoint is actually available before sending a request
• Check the shape and content of body of the response against expectations for the endpoint

Tasks ⚙️

Scoping 🔭

Some loose ideas:

• Look into helper functions from beekeper, nectar, rapid, etc.
• See how jq/jqr could help with inspecting or processing the WebAPI JSON

Development 👨‍💻

Documentation ✍️

• Create section in reference index page
• Write vignette on working with [AREA]