Build APIs that developers actually want to integrate with.

A poorly designed API costs every developer who integrates with it hours of frustration — and costs you integrations that never happened.

The quality of an API is measured by how quickly a developer can go from reading the documentation to making a successful API call. An API that requires three support tickets to integrate correctly will not be integrated by developers who have alternatives. An API without rate limiting will be abused until it falls over. An API without versioning will break integrations every time you make a change. These are not problems that can be fixed with better documentation — they are architectural decisions that must be made correctly before the first endpoint is written. PROPELOO treats API design as a product discipline: we design APIs from the consumer perspective, specify them in OpenAPI before implementing, and measure developer experience as a first-class metric.

The full API engineering stack.

A production API platform has seven components beyond the endpoints themselves.

System Layers

• API Design Layer: Resource modelling, endpoint design, request/response schema, error taxonomy, versioning strategy
• Implementation Layer: Business logic, validation, serialisation, pagination, filtering, sorting
• Security Layer: Authentication (OAuth 2.0, API keys, JWT), authorisation, rate limiting, input validation
• Gateway Layer: API gateway (Kong/AWS API Gateway), routing, load balancing, SSL termination, WAF
• Developer Experience Layer: OpenAPI documentation, interactive playground, SDKs, changelog, sandbox environment

Core Technical Capabilities

• API Design (OpenAPI-first)

  OpenAPI 3.1 specification written before implementation — resource naming, HTTP verb selection, request/response schema, error codes, pagination design (cursor vs offset), filtering patterns and hypermedia (HATEOAS where appropriate).

• REST API Engineering

  RESTful API with correct HTTP semantics, idempotency enforcement on mutation endpoints, consistent error responses (RFC 7807 Problem Details), ETag-based caching, conditional requests and content negotiation.

• GraphQL API Engineering

  GraphQL schema design, resolver optimisation with DataLoader (N+1 prevention), pagination (Relay cursor spec), subscriptions for real-time data, persisted queries, complexity limiting and depth limiting.

• Authentication & Authorisation

  OAuth 2.0 / OIDC for third-party access, API key management with scopes and expiry, JWT validation with correct algorithm enforcement, per-endpoint authorisation and audit logging for all API access.

• Rate Limiting & Quotas

  Per-API-key rate limiting (requests per second, requests per day), quota management with overage handling, burst allowances, rate limit headers (X-RateLimit-Remaining, Retry-After) and graceful degradation under load.

• Developer Experience

  Auto-generated OpenAPI documentation with Stoplight or Redoc, interactive API playground, code samples in 5+ languages, SDK generation (openapi-generator), changelog, webhook documentation and sandbox environment.

How we think about API engineering.

An API is a contract with every developer who integrates with it. Breaking that contract — even with good intentions — breaks their integration. Design for stability from the first endpoint.

• Design the spec before writing the code

  Writing the OpenAPI specification before implementation produces better API design because design is cheaper to iterate on than code. The spec review reveals resource naming inconsistencies, missing error cases and awkward response shapes before they are hardcoded. Consumer-driven contract testing (Pact) validates the implementation against the spec. API design reviewed as a pull request produces better APIs than API design discovered from reading the implementation.

  Axiom:

• Versioning is a commitment, not a feature

  An API without a versioning strategy will eventually break integrations. URL versioning (/v1/, /v2/) is explicit and easy to understand. Header versioning is cleaner but harder to test. Semantic versioning for APIs means: new endpoints and optional fields are non-breaking, removing endpoints or required fields is breaking. Define your versioning policy before v1 — the first version sets the expectation for how changes will be managed.

  Axiom:

• Rate limiting protects availability

  An API without rate limiting will be hammered by misconfigured clients, runaway scripts and deliberate abuse until it becomes unavailable for everyone. Rate limiting per API key (not just per IP — shared infrastructure means shared IPs) with clear headers (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) and a 429 response is a reliability feature, not a monetisation mechanism. Implement it before the first external integration.

  Axiom:

• Error responses are part of the interface

  An API that returns a 500 with {"error": "Something went wrong"} for every failure is not debuggable. RFC 7807 Problem Details provides a standard format for error responses that includes: type (a URI identifying the error class), title (human-readable), status (HTTP status code), detail (specific information about this instance), and instance (URI identifying this specific occurrence). Consistent, detailed error responses are the difference between a developer who integrates successfully in 30 minutes and one who files a support ticket.

  Axiom:

The API design decisions that define developer experience.

These choices cascade into every integration ever built on your API.

• REST vs GraphQL vs gRPC?

  Impact: REST for public/partner APIs — universal client support, excellent tooling. GraphQL for complex, multi-client data APIs where different clients need different data shapes. gRPC for internal microservice communication where performance and type safety matter. These are complements, not alternatives.

  • REST + OpenAPI — universal, well-understood, tooling-rich, correct for most public APIs
  • GraphQL — client-defined queries, flexible for complex data, over-fetching prevention
  • gRPC — typed, fast, streaming support, ideal for internal microservice communication
  • WebSocket / SSE — real-time use cases requiring push from server to client

• Authentication mechanism?

  Impact: OAuth 2.0 client credentials for server-to-server integrations. OAuth 2.0 auth code for APIs that act on behalf of users. API keys for developer tooling and simpler integrations where OAuth is overkill. Always use HTTPS — never expose API keys over plain HTTP.

  • API keys — simple, stateless, easy for developers, less granular than OAuth
  • OAuth 2.0 (client credentials) — machine-to-machine, fine-grained scopes
  • OAuth 2.0 (auth code flow) — user-delegated access, required for acting on behalf of users
  • JWT — stateless verification, no server-side session, good for internal APIs

• Versioning strategy?

  Impact: URL versioning for simplicity and testability. Stripe-style date versioning for mature platforms where the fine-grained deprecation communication is worth the added complexity. Agree on the strategy before v1 — changing versioning approaches breaks all existing documentation.

  • URL versioning (/v1/, /v2/) — explicit, easy to understand, easy to test
  • Header versioning (API-Version: 2024-01-01) — cleaner URLs, harder to test in browser
  • Query parameter versioning (?version=2) — simple, pollutes query params
  • Stripe-style date versioning — date-based, easy to deprecate, communicates stability

• Pagination approach?

  Impact: Cursor pagination for any collection that changes frequently (social feeds, transaction history). Offset for simple use cases with stable data. Never return unbounded collections — always paginate, always document the max page size.

  • Offset pagination (page=2&limit=20) — simple, breaks when items are inserted during pagination
  • Cursor pagination (after=cursor_id) — consistent across inserts/deletes, more complex
  • Keyset pagination (after_id=123) — database-efficient, consistent
  • No pagination — only for small, bounded result sets

• Rate limiting granularity?

  Impact: Per API key rate limiting is the correct default for authenticated APIs. Per-endpoint limits for expensive operations (bulk exports, report generation) that need separate quotas. Always include rate limit headers so clients can self-regulate.

  • Per IP — simplest, breaks behind shared NAT/proxy
  • Per API key — correct for authenticated APIs
  • Per endpoint — fine-grained, complex to manage
  • Per user + per endpoint — most granular, highest engineering cost

• Webhook vs polling?

  Impact: Webhooks for event-driven integrations where consumers need to react to changes. Include: signature verification (HMAC-SHA256), retry with exponential backoff, delivery status visibility and a webhook log UI in the developer dashboard.

  • Webhooks — real-time, efficient, requires HTTPS endpoint from consumer
  • Polling — simple for consumer, inefficient for provider, higher latency
  • Server-sent events — real-time push, browser-native, unidirectional
  • WebSocket — bidirectional real-time, higher complexity

What PROPELOO builds.

• Public API Platform

  REST API with OAuth 2.0, API key management, rate limiting, OpenAPI documentation, interactive playground, SDK generation and developer portal.

• Internal API Gateway

  Internal service API gateway — authentication, routing, rate limiting, observability and service discovery for microservices architecture.

• GraphQL API

  GraphQL API with schema design, DataLoader optimisation, subscriptions, complexity limiting, persisted queries and schema stitching for federated data.

• Webhook Infrastructure

  Webhook delivery system with HMAC signing, retry with exponential backoff, delivery status tracking, webhook log UI and dead letter queue for failed deliveries.

• API Migration

  Migrate legacy SOAP/RPC API to modern REST/GraphQL — consumer impact assessment, parallel versioning, migration guide and deprecation timeline.

• API Monetisation Platform

  API with usage-based billing — metered API key consumption, Stripe billing integration, usage dashboard, tier management and overage handling.

The API engineering stack.

Design, implementation, gateway and developer experience each require specific tooling.

• Implementation

  Stack: Node.js (Fastify/Express), Go (Gin/Fiber), Python (FastAPI), Java Spring Boot, Rust (Axum)

• API Standards

  Stack: OpenAPI 3.1, GraphQL (Apollo/Pothos), gRPC + Protobuf, AsyncAPI (webhooks/events)

• Auth

  Stack: Auth0, Keycloak, custom OAuth 2.0 server, API key service (custom), JWT (jose library)

• Gateway

  Stack: Kong Gateway, AWS API Gateway, Nginx, Traefik, Cloudflare Workers

• Developer Experience

  Stack: Stoplight (OpenAPI docs), Redoc, Scalar, openapi-generator (SDKs), Postman collections

• Monitoring

  Stack: Datadog APM, AWS API Gateway metrics, Custom request logging, Alerting on error rate, Latency percentile dashboards

API security is the perimeter of your platform.

Every API endpoint is an attack surface. Every unauthenticated endpoint is a public attack surface.

• Authentication Enforcement

  Every endpoint that returns or modifies data must require authentication. No unauthenticated endpoints in production except public read endpoints with explicitly justified business purpose. API keys must be hashed before storage — a database breach should not expose working API keys.

• Authorisation at the API Layer

  Authorisation logic belongs in the API layer, not only in the UI. A user who can call the API directly (e.g. via curl) must receive the same authorisation enforcement as a user clicking a button in the frontend. Resource-level authorisation (can this user access this specific resource?) must be validated on every request.

• Input Validation

  Every request parameter and body field must be validated before processing. JSON Schema validation via OpenAPI spec enforcement. String length limits, regex patterns for formatted fields, numeric range checks and enum validation. Reject unknown fields (strict mode) to prevent mass assignment vulnerabilities.

• Rate Limiting & Abuse Prevention

  Rate limiting per API key, per IP for unauthenticated endpoints, burst limiting for sudden spikes and per-endpoint limits for expensive operations. 429 responses with Retry-After header. Monitoring for unusual traffic patterns.

• Secrets in API Requests

  API keys and tokens must be in Authorization headers — never in query parameters (they appear in server logs and browser history), never in request body (harder to intercept but still poor practice). HTTPS everywhere — no HTTP for any endpoint that handles authentication tokens.

• Webhook Security

  Webhook consumers must verify request signatures (HMAC-SHA256 of request body with a shared secret) before processing. Unsigned webhooks can be spoofed by any party who knows the endpoint URL. Signature verification is the difference between a trusted event and an arbitrary HTTP request.

From design to production API platform.

1. 01. API Design

   OpenAPI specification written and reviewed before implementation — resource modelling, endpoint design, error taxonomy, versioning and pagination strategy.

2. 02. Authentication & Security

   OAuth 2.0 / API key implementation, authorisation framework, rate limiting and input validation middleware.

3. 03. Endpoint Implementation

   Business logic implementation validated against OpenAPI spec. Contract tests (Pact) verify spec conformance.

4. 04. Gateway & Infrastructure

   API gateway configuration, load balancing, SSL, CORS, WAF and CDN for public endpoints.

5. 05. Developer Experience

   Auto-generated documentation, interactive playground, code samples, SDK generation and sandbox environment.

6. 06. Webhook Infrastructure

   Webhook delivery system with signing, retry logic, status tracking and developer dashboard.

7. 07. Monitoring & Launch

   Request logging, latency dashboards, error rate alerting, API key usage analytics and rate limit monitoring.

Frequently Asked Questions