API Playground designed
The API reference renderer and the API playground are related, but they are not the same product capability.
Stoplight has a "Try It" capability, and that remains useful to evaluate. For GPUaaS, the key requirement is stronger: developers need a playground that can exercise the right environment with the right credentials and safety controls. A mock-backed Try It is helpful for learning request shape, but it does not prove auth, tenancy, idempotency, policy, billing, terminal, or operational behavior against a real GPUaaS control plane.
The current Stoplight Elements Research result is to pilot Elements as a renderer/mock-mode candidate, while keeping the GPUaaS playground as a controlled product surface.
Scalar is also a candidate for this layer. If Scalar's Docusaurus integration gives us a better embedded reference/playground experience, switching is viable as long as the same environment, credential, audit, and publication-track rules are satisfied.
The current Scalar Research result is to pilot Scalar beside Stoplight using the same synced OpenAPI artifact.
Reference vs Playground
| Capability | Purpose | Requirement |
|---|---|---|
| Static contract artifact | Download and inspect canonical OpenAPI/AsyncAPI YAML | Already implemented through /api/openapi.draft.yaml and /api/asyncapi.draft.yaml |
| Rendered API reference | Browse endpoints, schemas, examples, and auth rules | Can be Stoplight, Docusaurus OpenAPI Docs, Redoc/Swagger-style, or another renderer |
| Embedded API explorer | Browse reference and execute examples in the same portal path | Scalar or Stoplight Elements are candidates, pending security and environment-control review |
| Mock Try It | Learn request/response shape without touching a real environment | Useful for low-risk learning, not enough for integration validation |
| GPUaaS playground | Execute selected calls against approved dev/sandbox environments | Needed for internal developers, app teams, and integration validation |
Playground Requirements
| Area | Requirement |
|---|---|
| Environment routing | Explicit environment selector: mock, local/dev, shared sandbox, UAT, or partner sandbox |
| Credential model | Uses approved developer credentials, service-account tokens, or short-lived playground sessions |
| Tenant/project scope | Every request shows the active tenant/project context before execution |
| Safety | Mutating requests require confirmation, idempotency key visibility, and safe defaults |
| Secrets | Tokens are never persisted in docs storage, URLs, screenshots, or generated examples |
| Audit | Playground requests include correlation IDs and are distinguishable in logs/audit |
| Rate limits | Playground traffic has explicit rate limits and abuse controls |
| Examples | Examples come from OpenAPI plus curated runnable scenarios, not hand-written drift |
| Publication tracks | Public docs may allow mock only; internal/customer/partner tracks can expose controlled live environments |
First Playground Scenarios
| Scenario | Why it matters |
|---|---|
| Auth/token exchange or service-account token | Proves developer can authenticate safely |
| Catalog and SKU lookup | Safe read-only first call for all consumers |
| Launch precheck | Tests policy, balance, availability, and project context without provisioning |
| Allocation status lookup | Shows lifecycle state and error model |
| Idempotent mutation example | Teaches retry behavior with X-Idempotency-Key |
| Billing balance/usage read | Shows money fields, minor units, and authorization boundaries |
| Event sample lookup | Bridges REST reference and AsyncAPI/event documentation |
Implementation Direction
Start with an embedded reference renderer, but design the playground as a separate layer:
Decision
Do not treat Stoplight Try It alone as the final GPUaaS developer experience. Evaluate it as one possible renderer or mock mode, then define the GPUaaS playground as a controlled product surface with environment, credential, security, and audit rules.