1. Vision and target audience
Audience: internal developers, partners, public. Main use cases (5 max at MVP), direct competitors (RapidAPI listings, Postman public collections). Value proposition in 1 line.
API specification in 2026: Complete guide, REST/GraphQL, Budget
TL;DR (60 seconds)
- → An API is a product, not a backend. It must have its users (developers), its documentation, its pricing and its dedicated support.
- → The 4 technical pillars: authentication (OAuth2, API keys), rate limiting per plan, clear versioning, interactive documentation (Swagger/OpenAPI, Postman).
- → Public API MVP budget: 10-30k EUR (6-12 weeks), complete API with dev portal: 30-80k EUR (3-5 months).
- → Pricing model: usage-based (per request or per action), freemium per plan (N req/month), tiered (free < 10k, pro 10k-100k, enterprise custom).
An API requirements document must answer 3 questions at the same time: how developers integrate your API (DX — Developer Experience), how you monetize (pricing model), and how you ensure reliability (SLA, monitoring, versioning). APIs that fail generally ignore the first pillar: impossible to understand in under 10 minutes, outdated documentation, opaque errors.
Average budget observed
€10,000–€80,000
API MVP 10-30k EUR, complete API with dev portal 30-80k EUR, enterprise API 80-250k EUR.
Average delivery time
6–20 weeks
API MVP 6-12 weeks, complete API 12-20 weeks.
Standard specification structure
2. API design
REST (clear CRUD resources, standard HTTP verbs) vs GraphQL (mobile clients, variable shape needs) vs RPC/gRPC (internal microservices). Naming conventions (snake_case or camelCase depending on the target ecosystem), error structure (RFC 7807 Problem Details).
3. Authentication and authorization
Simple API keys (basic B2B), OAuth 2.0 + Client Credentials (enterprise integrations), stateless JWT (scalability), granular scopes (read/write per resource), secret rotation, IP whitelisting for sensitive clients.
4. Rate limiting and quotas
Limits per plan (free 1000/day, pro 100k/month, enterprise under contract), algorithms (token bucket, sliding window), rate headers (X-RateLimit-Remaining), 429 response with Retry-After. Rack Attack on the Rails side, API Gateway (Kong, AWS API Gateway) for more flexibility.
5. Documentation and developer portal
OpenAPI 3.0 spec (source of truth), interactive docs (Stoplight, ReadMe, Swagger UI), step-by-step tutorials, official SDKs (at least JS + Python + Ruby to start), public Postman collection, versioned changelog, system status (status.flowayz.com).
6. Versioning and compatibility
Strategies: URL versioning (/v1, /v2, readable but multiple), header versioning (cleaner, less explicit), date-based (/2026-04-01, GitHub-style). Deprecation policy (12 months minimum on paid endpoints), communication (emails, dashboard, Sunset headers).
7. Observability and SLA
Structured logs (Datadog, Papertrail), metrics (p50/p95/p99 latency, error rate, requests per endpoint), automatic alerting (PagerDuty), public status, SLA (99.9% standard, 99.95% pro, 99.99% enterprise with financial compensation).
8. Billing and usage meters
Metering: count each request (overhead < 5ms), real-time aggregation (Redis Streams), monthly billing, peak handling (hard-stop vs billed overage), real-time usage portal on the client side, alerts at 80% of quota.
9. Security
HTTPS mandatory, TLS 1.3, strict input validation (schema validation at the entry point), injection protection (SQL, NoSQL, command), CORS configurable per client, anti-brute-force rate limiting, immutable audit logs, annual pentest, SOC 2 compliance if targeting enterprise.
Written manually, this specification often takes dozens of hours. Flowayz generates it in a few minutes from your brief.
Generate my specification →Pitfalls to avoid
- Documentation written last: 80% of integrations are abandoned if the 'Hello World' takes more than 30 minutes.
- No official SDK: developers prefer a competing API that has an `npm install`.
- Breaking changes without versioning: a single incompatible change = all clients broken at the same time = business disaster.
- Rate limiting too strict at the free tier: evaluators do not have time to test before deciding to buy.
- No latency monitoring per endpoint: an endpoint that slows from 200ms to 2s goes unnoticed until churn.
Frequently asked questions
REST or GraphQL for an API in 2026?
REST remains the default choice for 80% of cases (simple, cacheable, universal, docs SEO). GraphQL excels when clients have highly variable shape needs (mobile apps, complex dashboards) or when several data sources must be aggregated. Rule: if your audience does not ask for GraphQL spontaneously, start with REST.
How do you price a public API?
Three proven models: (1) request-based freemium (free 1k/day, pro 100k/month at €29, enterprise custom), (2) per business action (per AI-generated spec, per issued invoice), (3) pure usage-based (N € / 1000 req). Tiered freemium plus overage is the most adopted for B2B SaaS in 2026. Target: free to pro at 10-15% conversion, pro to enterprise at 3-5%.
How long does it take to document an API properly?
OpenAPI spec plus basic interactive docs: 2-4 weeks in parallel with development. Full developer portal (tutorials, official SDKs, changelog, status page): 6-10 additional weeks. Common mistake: planning '1 week of docs at the end' — that never happens.
Should you publish a REST or gRPC API in 2026?
External public: REST (universal compatibility, HTTP caching, easy to debug). Internal microservices: gRPC (performance, strict contracts via protobuf). Rarely both at the same time. If in doubt, start with REST and migrate to gRPC only if benchmarks prove a need.
What is the difference between a public API spec and an internal API spec?
A public API targets third-party developers: documentation, SDKs, pricing, SLA, versioning, dedicated support. An internal API targets your own teams: light documentation, no pricing, relaxed versioning, support via Slack. The budget can range from 1x to 5x for the same technical endpoints depending on DX requirements.
Generate your specification in 5 minutes
Flowayz turns your brief into a complete professional specification using 22 AI assistants. Free for life, no credit card.
Open my free account →