PMM (And Portal) API documentation

User story:

User should be able to discover and understand PMM API better.

Currently there is no good examples how to use it, as well as documentation is hidden in "Model" field. Also API is not mentioned in the doc and there is no full example how to use it step by step.

 

UI/UX:

none

 

 

Acceptance criteria:

User could read about API in Documentation and manipulate PMM with API and without UI.

 

Out of scope:

Step by Step usage for all API.

Just a couple of examples and good Examples in Swagger should be there.

 

Suggested implementation:

Some improvements would be done here:

https://jira.percona.com/browse/PMM-8222

but we need to add Examples for API:

https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto#L213

https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto#L251

so it will be shown in Swagger.

For it we need to migrate grpc-gateway from 1.x to 2.x latest version.

 

How to test:

some script that would use examples and test API and results.

 

Details:

https://www.percona.com/doc/percona-monitoring-and-management/2.x/details/api.html

this should be improved with examples on how to use API.

 

We can use tools like
https://github.com/Mermade/widdershins
https://github.com/mermade/reslate
https://github.com/Redocly/redoc

 

Feedback from Steve:
Just to share I got more insight from Vadim for the things he's looking for to approve GA (which we'll also be backing up to Tech Preview over time) with regards to documentation:

clear API documentation with code examples
how users can leverage from the command line if applicable

Remember that swagger is our choice (engineering) so we will not consider pushing its limitations off to our users...we'll need to find another way to satisfy the criteria. 

 

Here are some examples provided of what we should be moving towards
https://documentation.tradier.com/brokerage-api/trading/place-option-order
or
https://alpaca.markets/docs/api-documentation/api-v2/orders/
 
with examples how to code, i.e
https://alpaca.markets/docs/api-documentation/how-to/account/

 

Alternatives to Swagger:

https://stackoverflow.com/questions/36634281/list-of-swagger-ui-alternatives