API concepts and authentication
Public descriptions and API access
Section titled “Public descriptions and API access”A public reference can describe an API that requires authentication. Reading its documentation grants no permission to call it. Each service owns its client keys, scopes, limits and lifecycle. Follow that service’s instructions to obtain access.
OpenAPI
Section titled “OpenAPI”OpenAPI describes operations, inputs, responses and security schemes. Its machine-readable contract has its own version. Changing the renderer does not change the API. A draft contract is not evidence of a deployed implementation.
Safe examples
Section titled “Safe examples”This example uses an inactive hostname and placeholder token; it sends nothing to production:
GET /example-items HTTP/1.1Host: api.example.invalidAuthorization: Bearer EXAMPLE_TOKEN_DO_NOT_USEStore real keys securely in the relevant server-side client, never in a public website or documentation.
Errors and limits
Section titled “Errors and limits”401 usually indicates missing or invalid authentication; 403 indicates insufficient permissions. A service can return 429 when a limit is exceeded. Follow the actual error format and retry rules of the API. Do not include sensitive data, tokens or internal stack traces in public issue reports.
© MiloslavHub · CC BY 4.0