Details

    • Epic
    • Status: Done
    • Medium
    • Resolution: Done
    • None
    • None
    • PMM ManageD
    • PMM API documentation
    • 0
    • Yes
    • Yes
    • [obsolete] Architecture & Foundation

    Description

      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

       

      Attachments

        Issue Links

          Activity

            People

              alexander.demidoff Alexander Demidoff
              denys.kondratenko Denys Kondratenko (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:

                Smart Checklist