Overview
The Municipality Platform API provides comprehensive access to municipality data, supporting both web admin interfaces and mobile applications. The API is built with security, scalability, and ease of use in mind.
🔐 Secure Authentication
Firebase Authentication with 6-month refresh tokens for seamless mobile experience
📱 Mobile Optimized
Dedicated mobile endpoints with efficient data delivery and caching
🌐 Multi-Municipality
Support for users following multiple municipalities with aggregated content
⚡ High Performance
Optimized queries with proper indexing and efficient data structures
Authentication
🔑 Firebase Authentication
All API endpoints use Firebase Authentication for secure, scalable user management. The system supports both admin users (web interfaces) and mobile app users with different permission levels.
Token Management
⏰ Token Expiration Strategy
- Access Tokens: 1 hour expiration (short-lived for security)
- Refresh Tokens: 6 months expiration (long-lived for convenience)
- Auto-refresh: Mobile apps automatically refresh tokens in background
- Revocation: Tokens can be instantly revoked for security
Admin Authentication
Admin endpoints require Firebase ID tokens with admin privileges:
- Super Admin: Full system access
- Municipality Admin: Access to specific municipality data
- Token Source: Web admin interfaces (super-admin, municipality apps)
Authorization: Bearer <firebase_id_token>
Mobile Authentication
Mobile endpoints use Firebase ID tokens from mobile app authentication:
- User Registration: Handled by mobile app with separate database
- Token Management: Firebase SDK handles token refresh automatically
- Session Duration: Users stay logged in for 6 months
- Security: Short-lived access tokens with automatic refresh
Authorization: Bearer <firebase_id_token>
Best Practices
- Store refresh tokens securely on device
- Implement automatic token refresh before expiration
- Handle token expiration gracefully with re-authentication
- Use Firebase SDK for token management
- Never store tokens in localStorage (use secure storage)
API Endpoints
Public Endpoints
No authentication required - accessible to all users
GET
/api/public/municipalities
Get list of all municipalities with basic information
GET
/api/public/municipalities/{id}
Get detailed information about a specific municipality
Mobile Endpoints
Require Firebase authentication - for mobile app users
GET
/api/mobile/news
Get news from followed municipalities
GET
/api/mobile/events
Get events from followed municipalities
POST
/api/mobile/follow
Follow a municipality
DELETE
/api/mobile/follow/{municipalityId}
Unfollow a municipality
Admin Endpoints
Require admin authentication - for web admin interfaces
GET
/api/admin/news
Get all news (super admin) or municipality news (municipality admin)
POST
/api/admin/news
Create new news article
GET
/api/admin/events
Get all events (super admin) or municipality events (municipality admin)
POST
/api/admin/events
Create new event
Code Examples
Mobile App Authentication
JavaScript/TypeScript (React Native)
// Initialize Firebase
import auth from '@react-native-firebase/auth';
// Sign in user
const signIn = async (email: string, password: string) => {
try {
const userCredential = await auth().signInWithEmailAndPassword(email, password);
const token = await userCredential.user.getIdToken();
return token;
} catch (error) {
console.error('Sign in error:', error);
}
};
// Get current token (auto-refreshed)
const getCurrentToken = async () => {
const user = auth().currentUser;
if (user) {
return await user.getIdToken();
}
return null;
};
// API call with authentication
const fetchNews = async () => {
const token = await getCurrentToken();
const response = await fetch('https://api.dimotis.com/api/mobile/news', {
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
});
return response.json();
};
Error Handling
Handling Authentication Errors
const handleApiError = (error) => {
switch (error.code) {
case 'TOKEN_EXPIRED':
// Token expired - refresh automatically
return refreshToken();
case 'TOKEN_REVOKED':
// Token revoked - redirect to login
return redirectToLogin();
case 'INVALID_TOKEN':
// Invalid token - redirect to login
return redirectToLogin();
default:
// Other errors
console.error('API Error:', error);
}
};
Following Municipalities
Follow/Unfollow Municipality
// Follow a municipality
const followMunicipality = async (municipalityId: string) => {
const token = await getCurrentToken();
const response = await fetch('https://api.dimotis.com/api/mobile/follow', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ municipalityId })
});
return response.json();
};
// Unfollow a municipality
const unfollowMunicipality = async (municipalityId: string) => {
const token = await getCurrentToken();
const response = await fetch(`https://api.dimotis.com/api/mobile/follow/${municipalityId}`, {
method: 'DELETE',
headers: {
'Authorization': `Bearer ${token}`
}
});
return response.json();
};
Error Handling
HTTP Status Codes
- 200 Success
- 201 Created
- 400 Bad Request - Invalid input
- 401 Unauthorized - Authentication required
- 403 Forbidden - Insufficient permissions
- 404 Not Found - Resource doesn't exist
- 500 Internal Server Error
Authentication Error Codes
- TOKEN_EXPIRED: Access token has expired (refresh automatically)
- TOKEN_REVOKED: Token has been revoked (re-authenticate)
- INVALID_TOKEN: Token is malformed or invalid (re-authenticate)
- AUTH_FAILED: General authentication failure
Error Response Format
{
"error": "Unauthorized - Token expired",
"message": "Your session has expired. Please refresh your token or log in again.",
"code": "TOKEN_EXPIRED"
}
Rate Limiting
To ensure fair usage and prevent abuse, the API implements rate limiting:
- Public endpoints: 100 requests per minute per IP
- Mobile endpoints: 1000 requests per minute per user
- Admin endpoints: 500 requests per minute per user
- Burst allowance: Up to 200% of limit for short periods
Rate Limit Headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
API Specification
Direct links to the OpenAPI specification in different formats:
GET
/openapi.yaml
OpenAPI 3.0.3 specification in YAML format
GET
/openapi.json
OpenAPI 3.0.3 specification in JSON format
# Direct API Specification URLs
YAML: https://api.dimotis.com/openapi.yaml
JSON: https://api.dimotis.com/openapi.json
# For mobile app development tools
# Use these URLs in tools like:
# - Postman (Import API)
# - Insomnia
# - Swagger Codegen
# - OpenAPI Generator
# - React Native API client generators
Mobile App Integration
For mobile app development, you can use these specification URLs to:
- Generate API clients: Use tools like OpenAPI Generator to create TypeScript/JavaScript clients
- Import into development tools: Postman, Insomnia, and other API testing tools
- Auto-generate types: Create TypeScript interfaces from the specification
- Documentation: Keep your mobile app documentation in sync with the API
Example: Generate TypeScript Client
# Using OpenAPI Generator
npx @openapitools/openapi-generator-cli generate \
-i https://api.dimotis.com/openapi.yaml \
-g typescript-fetch \
-o ./api-client
# Using Swagger Codegen
npx swagger-codegen-cli generate \
-i https://api.dimotis.com/openapi.yaml \
-l typescript-fetch \
-o ./api-client
Best Practices
Mobile App Development
- Use Firebase SDK for authentication and token management
- Implement automatic token refresh before expiration
- Store refresh tokens securely (Keychain on iOS, Keystore on Android)
- Handle network errors gracefully with retry logic
- Cache data locally for offline functionality
- Implement proper error handling for all API calls
Security
- Never store tokens in localStorage or insecure storage
- Always use HTTPS for all API communications
- Validate all user input before sending to API
- Implement proper session management
- Use secure storage for sensitive data
Performance
- Implement proper caching strategies
- Use pagination for large data sets
- Optimize image loading and storage
- Implement offline-first architecture
- Use efficient data structures
Changelog
December 2024
v1.0.0
Initial Release
- Firebase Authentication with 6-month refresh tokens
- Public endpoints for municipality discovery
- Mobile endpoints for news and events
- Admin endpoints for content management
- Comprehensive error handling and rate limiting
- OpenAPI 3.0 specification with Swagger UI
December 2024
v1.1.0
Planned Features
- Survey submission and management
- Lost & Found item management
- Push notifications for news and events
- Advanced analytics and reporting
- Multi-language support
Support
For technical support, questions, or feature requests, please contact: