Getting Started
Providing the basic steps of how an API consumer can get started using an API with as few steps as possible is essential for any API. Like other common properties, a getting started isn't just for API consumers to understand how to onboard, and it is about pushing API producers to simply and reduce friction when it comes to onboarding.
Also known as: Quickstart, Quick Start, Onboarding, First Call
Example
Standards
- OpenAPI Initiative OpenAPI Specification 3.1
- Schema.org Schema.org HowTo
- Postman Postman Collection Format v2.1
- CommonMark CommonMark 0.31
- De facto cURL
- De facto HTTPie
OpenAPI Expression
-
servers(OpenAPI 3.x) — Base URLs used in the first-call example. -
components.securitySchemes(OpenAPI 3.x) — Auth mechanism the quickstart walks through. -
components.examples(OpenAPI 3.x) -
paths.*.*.requestBody.content.*.example(OpenAPI 3.x) — Inline request example used in walkthroughs. -
paths.*.*.responses.*.content.*.example(OpenAPI 3.x) -
x-codeSamples(Redoc / Redocly vendor extension) — Per-operation curl/SDK samples rendered alongside the reference.
Governance Rules
operation-success-response(Spectral built-in) — Operations must define a successful response so quickstarts can show a meaningful body.oas3-valid-media-example(Spectral built-in) — Inline examples must validate against their schema.oas3-server-not-example.com(Spectral built-in) — Quickstarts need a real, callable base URL.info-contact(Spectral built-in) — Quickstart pages typically link to `info.contact` for help.
Risk & Compliance
Compliance:
- Accessibility (WCAG 2.2) — onboarding flows are a first-impression surface
- Terms-of-Service acceptance must be explicit before issuing keys
Security: Quickstarts frequently leak credentials when contributors paste live tokens into examples; prefer placeholders and key-redaction tooling. "Curl in 30 seconds" flows that skip TLS verification or hard-code admin scopes train consumers into insecure habits.
Tools
- Postman — Collections and Run-in-Postman
- Insomnia — API client
- Hoppscotch — API client (MIT)
- HTTPie — CLI client (BSD-3-Clause)
- curl — CLI client (curl)
- Bruno — API client (MIT)
Suggested Metrics
time_to_first_hello_world— Median time from signup to first successful 2xx response (TTFHW).signup_to_first_call_funnel— Stepwise conversion across signup, key creation, and first authenticated call.quickstart_completion_rate— Fraction of new accounts that finish the documented quickstart steps.copy_button_click_rate— Engagement with copyable curl / SDK snippets on the quickstart page.
Example Implementations
- Stripe — Test-mode keys preloaded into curl/SDK samples so a first charge works without signup friction.
- Twilio — Send-an-SMS-in-five-minutes quickstart across multiple language tabs.
- OpenAI — API key creation, environment variable, first completion in three steps.
- GitHub — Personal access token plus curl call to /user as a canonical first request.
Related Properties
Tags
- Onboarding
- Authentication
- Documentation