This page covers technical considerations for developers building fediverse tools, timeline applications, or integrations with Mastodon and other ActivityPub platforms.
API Basics
Mastodon API
Mastodon provides a comprehensive REST API for client development:
- Authentication: OAuth 2.0 with scopes for read/write/follow/push
- Rate limiting: Varies by instance, typically 300 requests per 5 minutes
- Pagination: Uses Link headers with max_id/min_id/since_id parameters
- Streaming: WebSocket connections for real-time updates
The API is well-documented and relatively stable. Most non-Mastodon fediverse platforms implement compatible APIs.
ActivityPub
For server-to-server communication or building federating services:
- Actor model: Users, services, and other entities are “actors” with inboxes/outboxes
- Activities: Actions (Create, Like, Announce, Follow) wrapped in standard formats
- Objects: Posts, images, and other content in standardized representations
- HTTP Signatures: Request authentication between servers
ActivityPub is more complex than client APIs but enables true federation.
Timeline Implementation
Fetching Timelines
Basic timeline fetching:
GET /api/v1/timelines/home
GET /api/v1/timelines/public (federated)
GET /api/v1/timelines/public?local=true (local)
Handle pagination properly—timelines can be long, and you’ll need to fetch pages as users scroll.
Real-Time Updates
For live-updating timelines, use streaming:
wss://instance.example/api/v1/streaming?stream=user
Events include new posts, notifications, and deletions. Handle reconnection gracefully.
Caching Strategies
Timeline data benefits from smart caching:
- Cache post content: Posts rarely change after creation
- Invalidate on updates: Handle edits and deletions
- Prefetch on scroll: Anticipate pagination
- Respect rate limits: Don’t refetch unchanged data
Consider using ETags and conditional requests to minimize unnecessary data transfer.
Authentication and Authorization
OAuth 2.0 Flow
- Register your application with the instance
- Redirect users to the instance’s authorization page
- Handle the callback with the authorization code
- Exchange for tokens (access token + refresh token)
- Use access token in Authorization header
Request minimal scopes. If you only need to read, don’t request write access.
Token Management
- Store tokens securely (encrypted at rest)
- Handle token expiration and refresh
- Revoke tokens when users disconnect
- Don’t log tokens in plain text
Multi-Instance Support
Fediverse apps often need to work with many instances:
- Store instance URL alongside credentials
- Handle different instance configurations
- Account for feature differences between instances
- Verify instance compatibility before operations
Rate Limiting and Quotas
Respecting Limits
Most instances enforce rate limits. Handle them properly:
- Check for 429 responses
- Read the Retry-After header
- Implement exponential backoff
- Queue requests during heavy operations
Burst vs Sustained
Rate limits often have two components:
- Burst limit (short-term)
- Sustained limit (longer-term)
Design your request patterns to stay within both.
Instance Variation
Different instances may have different limits. Don’t assume all instances match mastodon.social’s limits.
Privacy and Data Handling
Data Minimization
Collect only what you need:
- Don’t cache content you don’t use
- Delete data when users disconnect
- Respect post visibility settings
- Honor content warnings in your display
Logging
Be careful what you log:
- Don’t log access tokens
- Avoid logging post content in production
- Anonymize user identifiers in analytics
- Implement log retention policies
User Data Requests
Be prepared to:
- Export user data on request
- Delete user data on request
- Explain what data you store
Federation Considerations
Eventual Consistency
The fediverse is eventually consistent:
- Engagement counts may be incomplete
- Replies may arrive out of order
- Old posts from new follows may be missing
- Deletions may not propagate everywhere
Design your application to handle incomplete information gracefully.
Instance Blocking
Your users’ instances may block other instances:
- Content from blocked instances won’t appear
- Users from blocked instances can’t interact
- Your app should handle missing content gracefully
Federation Lag
Content doesn’t appear instantly across instances:
- New follows may take time to propagate
- Posts may arrive with delay
- Boosts help content spread faster
Safe Defaults
Read-Only When Possible
If your tool only needs to read, don’t request write permissions. This limits potential damage if compromised.
Fail Closed
When in doubt, don’t post or take action. It’s better to fail silently than to post unintended content.
Confirm Destructive Actions
Before deleting posts, unfollowing, or other destructive actions, confirm with the user.
Graceful Degradation
When API calls fail, your app should remain usable:
- Show cached content if fresh data unavailable
- Queue actions for retry
- Inform users of temporary issues
Working with Open Source
The fediverse is built on open source. Contributing effectively:
Issue Reporting
Good bug reports include:
- Clear reproduction steps
- Expected vs actual behavior
- Instance and client versions
- Relevant logs (sanitized)
Contributing Code
Before submitting changes:
- Read contribution guidelines
- Follow code style conventions
- Include tests when possible
- Document your changes
Community Norms
The fediverse has strong community norms:
- Respect existing architectural decisions
- Discuss significant changes before implementing
- Be patient with volunteer maintainers
- Credit prior work appropriately
For general guidance on open source contribution workflows, GitHub’s first contributions guide provides a good introduction.
Testing
Test Instances
Use test instances for development:
- Don’t test on production instances
- Some developers run local instances
- Test against multiple implementations
Mock Data
Create realistic test data:
- Various post types (text, media, polls)
- Different visibility levels
- Edge cases (very long posts, many attachments)
- Unicode and emoji handling
Federation Testing
Testing federation is harder:
- Requires multiple instances
- Latency and timing issues
- Network failure scenarios
Some test suites exist, but federation testing remains challenging.
Performance
Efficient Requests
Minimize API calls:
- Use pagination efficiently
- Batch operations when possible
- Cache aggressively with proper invalidation
- Use streaming instead of polling when available
Media Handling
Media (images, video) requires care:
- Respect content type and size limits
- Implement lazy loading
- Consider bandwidth-limited users
- Cache media appropriately
Memory Management
Timeline applications can consume significant memory:
- Virtual scrolling for long lists
- Unload off-screen content
- Set reasonable cache limits
- Profile memory usage regularly
Frequently Asked Questions
For client applications, use the Mastodon API (or compatible). ActivityPub is for server-to-server communication or building federating services.
Start with Mastodon API compatibility. Many platforms implement it. Add platform-specific features only if needed for your use case.
Run local test instances of Mastodon (or other software). Docker makes this relatively straightforward. Some test suites and mocking tools also exist.
Requesting excessive permissions, ignoring rate limits, not handling federation lag, caching data you shouldn't, and not testing with multiple instances.
The Mastodon Discord and various fediverse development communities are active. Check GitHub discussions for specific projects. Be specific in your questions.
Related Resources
- What is the Fediverse? — Federation concepts explained
- How Algorithmic Timelines Work — Timeline design principles
- Best Tools for Mastodon — Existing tools for reference
- Plus Features — Advanced timeline feature concepts