[DOC] Document API for Push and Querrier services

[cyriltovena]

We currently don't have good documentation for the connect API specially the Push and Querier services.

We should definitively document to make integrations with language and other system easier.

[simonswine]

If possible I would like to build on top of the OpenAPI spec.

Right now we only export the directly mounted endpoints:

https://elements-demo.stoplight.io/?spec=https://raw.githubusercontent.com/grafana/pyroscope/next/api/openapiv2/gen/phlare.swagger.json#/schemas/v1Series

[cyriltovena]

I think it might be due because we don't have http option on the proto like the agent.

We don't use those GRPC gateway endpoint ourselves? I wonder if we should use it ?

[simonswine]

I still think we should distinguish clearer between external API surface (something like /ingest, and the QuerierService) and internal API (anything connect go).

For the internal API surface, no guarantees at all, for the external ones we should focus on stability with all our decision and maybe even mount it under a versioned prefix.

[tomershafir]

@simonswine hey, following slack, imo you have to maintain a stable external api, REST and/or GRPC (I would consider supporting both). Otherwise, developers will have hard time building tools around pyroscope, thus damaging the potential ecosystem.

As part of that, you should maintain a unified human/machine readable documentation. I think OpenAPI for REST and proto(/flatbuffers, better though probably harder to use) for GRPC are great de facto standards which should be used.

For context, my interest here is https://github.com/metrico/qryn.

[pnf]

There used to be documentation of a REST api at least as of version 0.37, but the old doc pages now redirect to a grafana advertisement. We figure can infer it from ingest_pprof_test.go, ingest_handler_test, and the sample data, but why are you making us do this?