API
This document defines the API architecture, standards, conventions, security model, versioning strategy, and implementation guidelines for MHMD Studio. APIs are treated as stable products that serve web applications, AI agents, internal tools, future mobile applications, and third-party integrations.
Document Metadata
| Property | Value |
|---|---|
| Document | API |
| Version | 1.0 |
| Status | Active |
| Owner | Mohammed El Maachi |
| Last Updated | July 2026 |
Purpose
The API layer exposes business capabilities while protecting internal implementation details.
Its objectives are to:
- Provide consistent interfaces.
- Enforce business rules.
- Support multiple clients.
- Simplify integrations.
- Enable AI agents.
- Maintain security and performance.
The API is the contract between systems.
API Philosophy
Every endpoint should be:
- Predictable
- Consistent
- Versionable
- Secure
- Well documented
- Observable
- Testable
The API should remain stable even when the underlying implementation changes.
Architectural Style
Primary architecture:
REST
Future additions:
- GraphQL (internal)
- Webhooks
- Realtime subscriptions
- AI endpoints
- Streaming responses
REST remains the default interface.
Base URL
Production:
text
https://api.mhmd.studioDevelopment:
text
http://localhost:3000/apiAll endpoints should exist under a common API namespace.
Versioning
Version APIs using the URL.
Example:
text
/api/v1/projects
/api/v1/articles
/api/v1/contactBreaking changes require a new major version.
Non-breaking improvements should remain within the current version.
Resource Naming
Use plural nouns.
Examples:
text
/projects
/articles
/services
/resources
/usersAvoid verbs in endpoint names.
HTTP Methods
| Method | Purpose |
|---|---|
| GET | Retrieve data |
| POST | Create resources |
| PUT | Replace resources |
| PATCH | Partial updates |
| DELETE | Remove resources |
Methods should follow standard HTTP semantics.
Response Format
Successful responses should use a consistent structure.
Example:
json
{
"success": true,
"data": {},
"meta": {}
}Error responses should follow the same overall structure.
Error Format
Example:
json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The submitted data is invalid."
}
}Do not expose stack traces or internal implementation details.
HTTP Status Codes
Use standard status codes.
Examples:
- 200 OK
- 201 Created
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 409 Conflict
- 422 Validation Error
- 429 Too Many Requests
- 500 Internal Server Error
Avoid inventing custom status codes.
Authentication
Authentication is handled through:
- Supabase Auth
- JWT Access Tokens
- Secure Cookies (where appropriate)
Sensitive endpoints must require authentication.
Authorization
Authorization should follow Role-Based Access Control (RBAC).
Example roles:
- Public
- User
- Admin
Permissions should follow the principle of least privilege.
Public Endpoints
Public endpoints may include:
- Services
- Portfolio
- Articles
- Resources
- Search
Public endpoints should remain read-only.
Protected Endpoints
Protected endpoints include:
- Dashboard
- Admin
- Content Management
- Analytics
- AI Configuration
- Internal APIs
Every protected request must verify authorization.
Pagination
Large collections should support pagination.
Parameters:
text
?page=1
&limit=20Metadata should include:
- Current page
- Total pages
- Total items
Filtering
Support filtering where appropriate.
Examples:
text
?category=design
?year=2026
?featured=true
?technology=nextjsFilters should remain composable.
Sorting
Support sorting through query parameters.
Example:
text
?sort=published_at
?order=descSearch
Search endpoints should support:
- Full-text search
- Category filtering
- Tag filtering
- Pagination
Future versions may support semantic search.
Validation
Validate all incoming requests.
Validation should occur before business logic executes.
Return meaningful validation messages.
Rate Limiting
Protect endpoints from abuse.
Suggested limits:
- Public API: moderate
- Authentication: strict
- AI endpoints: configurable
Rate limits should return HTTP 429.
File Uploads
Supported uploads include:
- Images
- Documents
- Project Assets
Requirements:
- File validation
- Size limits
- MIME validation
- Virus scanning (future)
Store files outside the database.
AI Endpoints
Future AI endpoints may include:
- Content Generation
- Summarization
- Prompt Execution
- Semantic Search
- Recommendation Engine
- Research Assistant
AI responses should clearly indicate generated content where appropriate.
Webhooks
Future integrations should support outbound webhooks.
Examples:
- Contact form submissions
- Project events
- Publishing events
- AI workflow completion
Webhook deliveries should be signed.
Observability
Every request should support:
- Request ID
- Structured logging
- Performance timing
- Error tracking
Logs should never contain secrets.
Documentation
Every endpoint should document:
- Purpose
- Authentication
- Parameters
- Request example
- Response example
- Error responses
- Rate limits
Documentation should be generated automatically whenever possible.
API Performance
Objectives:
- Low latency
- Efficient queries
- Response caching
- Compression
- Minimal payload size
Performance should be measured continuously.
Deprecation Policy
Deprecated endpoints should:
- Remain functional during the transition period.
- Be documented.
- Return deprecation warnings where appropriate.
- Include migration guidance.
Breaking removals require advance notice.
API Testing
Every endpoint should include:
- Unit tests
- Integration tests
- Authentication tests
- Authorization tests
- Validation tests
- Performance tests
Critical endpoints should include end-to-end coverage.
AI Compatibility
APIs should be designed for both humans and AI agents.
Responses should be:
- Structured
- Predictable
- Machine-readable
- Self-consistent
Avoid ambiguous response formats.
API Quality Checklist
Before publishing an endpoint verify:
- Naming follows conventions.
- Validation is complete.
- Authentication enforced.
- Authorization enforced.
- Errors documented.
- Tests pass.
- Documentation updated.
- Logging configured.
- Performance reviewed.
Final Principle
An API should be treated as a long-term contract.
Stability, clarity, and consistency are more valuable than rapid iteration.