Skip to content

docs(readiness): declare a public graphql api, a grpc call, and a key in the body - #359

Closed
auscaster wants to merge 1 commit into
mainfrom
docs/readiness-grpc-graphql
Closed

auscaster wants to merge 1 commit into
mainfrom
docs/readiness-grpc-graphql

Conversation

@auscaster

Copy link
Copy Markdown
Member

Three corrections to the listing guide, matching Catalog's contract (verifier 1.1.27):

  • GraphQL. A public GraphQL API is declared like any JSON API: a POST with a JSON body. The guide used to say to leave out an interface that is GraphQL alone, which would grade a vendor's only interface F. The exception that remains is a second interface that is GraphQL inside a self-hosted product.
  • gRPC. A gRPC call is declared with the application/grpc body format: a POST to the method's path, e.g. /modal.client.ModalClient/SandboxCreate.
  • Key in the body. Where a vendor takes its key in the request body rather than a header, the operation's body names that field: { media_type: application/json, credential_field: api_key }, as Amplitude's does. OpenAPI has no security scheme for a key in the body, so without this the vendor's own document can't say the request needs one.

@sourcey

sourcey Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

A maintainer will review your pull request

Sourcey can't admit this change automatically, so a maintainer reviews it. You don't need to do anything.

Follow your pull request on Sourcey

! A maintainer reviews this change.

  • The pull request changes more than the repository's data or one declared pin.

… in the body

The guide told contributors to leave out an interface that is GraphQL alone. Only a second interface that is GraphQL inside a self-hosted product is left out; a public GraphQL API answers the probe like any JSON API, and leaving out a vendor's only interface would grade it F. A gRPC call is declared with the application/grpc body format. Where the vendor takes its key in the request body, the operation's body names that field, since OpenAPI cannot state such a key as a security scheme.

Signed-off-by: Kam <oss@0state.com>
@auscaster
auscaster force-pushed the docs/readiness-grpc-graphql branch from bdcd71f to 6acb7a7 Compare October 12, 2026 10:10
@sourcey

sourcey Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

A maintainer will review your pull request

Sourcey can't admit this change automatically, so a maintainer reviews it. You don't need to do anything.

Follow your pull request on Sourcey

! A maintainer reviews this change.

  • The pull request changes more than the repository's data or one declared pin.

@auscaster

Copy link
Copy Markdown
Member Author

Folded into #394, which carries this change with the other CONTRIBUTING updates so they land in one review.

@auscaster auscaster closed this Oct 14, 2026
@auscaster
auscaster deleted the docs/readiness-grpc-graphql branch October 16, 2026 04:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant