SpeedPy API vs Rolling Your Own

Overview¶

SpeedPy gives you production-grade API infrastructure out of the box. This page clarifies where the boilerplate ends and where your team's work begins, so you can plan your integration effort accurately.

What SpeedPy provides¶

These capabilities ship with the boilerplate and work immediately after init-docker.sh or init-local.sh:

API framework & documentation¶

Django REST Framework with drf-spectacular
Auto-generated OpenAPI 3.0 schema at /api/schema/
Swagger UI (/api/docs/) and ReDoc (/api/redoc/)
Integration manifest at /.well-known/speedpy.json
URL-path versioning (/api/v1/...) with deprecation header pattern

Authentication & authorization¶

Session auth (browser), JWT (first-party clients), PATs (automation), OAuth2 (third-party apps)
OAuth2 Authorization Code + PKCE, Device Code grant, Dynamic Client Registration
Scope system with HasScope permission class
MFA gate on JWT issuance
Built-in scopes: read:profile, write:profile, read:teams, write:teams, read:products, read:webhooks, write:webhooks, admin

Teams & tenancy¶

Team model with owner/admin/member roles
Invitation flow with API endpoints
TeamModel base class for tenant-scoped resources
Team-scoped API permissions

Webhooks¶

Subscription management API (CRUD + test endpoint)
HMAC-signed payloads (X-SpeedPy-Signature)
At-least-once delivery with exponential backoff and dead-letter queue
Delivery logs and automatic subscription disabling on repeated failure
Event taxonomy with v1 events for teams and user profiles

Operational features¶

Rate limiting with X-RateLimit-* headers and 429 Retry-After
Request correlation IDs (X-Request-ID) bound to structured logs
Idempotency keys on selected POST endpoints
Page-number and cursor pagination

Starter examples¶

MCP server for AI assistants (Claude, Cursor)
MCP tool generator from OpenAPI schema
CLI with PAT and device-flow auth

What teams still build¶

The boilerplate provides infrastructure, not business logic. Fork owners design and implement:

Area	What you build	SpeedPy helps with
Business resources	Your domain models and API endpoints (invoices, orders, projects, etc.)	DRF serializers, viewsets, router registration, auto-schema
Custom scopes	Scope entries for your resources (e.g. `read:invoices`)	`OAUTH2_PROVIDER["SCOPES"]` registry, `HasScope` permission class
Domain webhook events	Events for your resources (e.g. `invoice.paid`, `order.shipped`)	`WebhookEvent` registry, `dispatch_event()`, delivery infrastructure
Business authorization	Who can access what beyond team membership (row-level permissions, feature flags)	Team roles, `TeamModel` tenant scoping
Provider-specific integrations	Stripe, Twilio, Salesforce, etc.	OAuth2 and PAT infrastructure for your own API consumers
SLAs & uptime guarantees	Response time targets, availability commitments	Rate limiting, health endpoint, structured logging
Deployment & compliance	HTTPS, CSP, GDPR, SOC2, deployment automation	Security middleware, `SecurityMiddleware`, `django-csp` integration
Custom automation workflows	n8n/Make.com/Zapier scenario design	Automation platform guide, OAuth2 + PAT auth

Decision guide¶

Situation	Recommendation
You need a REST API with auth, docs, and webhooks	Use SpeedPy as-is — add your endpoints
You need custom auth flows (SAML, LDAP)	Extend SpeedPy — allauth supports additional providers
You need GraphQL instead of REST	SpeedPy's auth and team infrastructure still applies; add `graphene-django` alongside DRF
You need a completely different API framework (FastAPI, etc.)	Roll your own — SpeedPy's value is in the Django/DRF integration
You need real-time data beyond webhooks	SpeedPy includes Django Channels for WebSocket support alongside webhooks

Time saved¶

Building the equivalent infrastructure from scratch typically involves:

Auth stack (session + JWT + PAT + OAuth2 + MFA): weeks of development and security review
Webhook system (subscriptions, signing, retries, DLQ): 1-2 weeks
API infrastructure (versioning, rate limiting, pagination, correlation IDs, idempotency): 1-2 weeks
OpenAPI/docs/manifest: days of configuration and testing
MCP server integration: days of protocol implementation

SpeedPy ships all of this pre-built and tested. Your team focuses on domain logic from day one.