Skip to main content

API Architecture & Guidelines

One ecosystem. Clear interfaces. Composable services.

APIs are the communication layer between Ubujima applications, services and platform capabilities.

As the ecosystem evolves, well-defined interfaces should allow AfroCom, Ma'at AI, Maji and future applications to interact without requiring every component to understand the internal implementation of another component.

API-First Principle​

Applications should depend on stable contracts rather than internal implementation details.

For example, a client may conceptually request:

GET /users/{id}

without needing to know how that capability is stored, deployed or implemented internally.

This separation makes it possible to improve internal services while minimizing unnecessary changes to clients.

Service-Oriented API Direction​

The long-term direction is a set of clear service interfaces behind a controlled entry layer.

                 Clients
                    │
                    ▼
            API / Entry Layer
                    │
       ┌────────────┼────────────┐
       │            │            │
       ▼            ▼            ▼
   Identity      Content      Discovery
       │            │            │
       └────────────┼────────────┘
                    │
             Other Services

The entry layer may provide common concerns such as routing, authentication enforcement, authorization, rate limits, validation, versioning and observability.

Business logic should remain in the appropriate service domain rather than accumulating in the gateway.

Domain Ownership​

Each service should have a clearly defined responsibility.

Potential API domains include:

  • Identity & Access — identity, sessions and permissions
  • Profiles — profile and social-relationship capabilities
  • Content — posts, comments, reactions and content workflows
  • Discovery — search, location-aware discovery and recommendations
  • Communication — messaging and real-time interaction
  • Notifications — user-facing notifications and alerts
  • Organizations & Opportunities — businesses, organizations, projects and opportunities
  • AI — reusable intelligence capabilities from Ma'at AI
  • Decentralized Services — Maji-enabled capabilities where appropriate

Domains may evolve as product requirements become clearer.

API Design Principles​

Ubujima APIs should aim for:

  • Clear resource and action naming
  • Consistent request and response structures
  • Explicit validation
  • Predictable error handling
  • Appropriate authorization
  • Backward compatibility where practical
  • Versioning when required
  • Idempotency for operations that may be retried
  • Pagination for large collections
  • Observability and traceability
  • Useful documentation

Authentication and Authorization​

API design must distinguish between:

  • Authentication — establishing identity
  • Authorization — determining what that identity may access or perform

Sensitive operations must enforce authorization at the appropriate service boundary.

Validation​

APIs should validate incoming data before processing it.

Validation may include:

  • Required fields
  • Data types
  • Length and format restrictions
  • Allowed values
  • Ownership
  • Permissions
  • Business rules
  • Security constraints

Invalid requests should return consistent and understandable responses.

Error Handling​

Errors should be useful to developers without exposing sensitive internal information.

A conceptual response may include:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource could not be found."
  }
}

Detailed stack traces, secrets, internal topology and other sensitive implementation information should not be returned to clients.

Versioning​

Where compatibility requires explicit versioning, an API may use a structure such as:

/api/v1/...

Versioning should be introduced intentionally rather than used as a substitute for careful API evolution.

Pagination and Filtering​

Large collections should support predictable pagination and, where appropriate, filtering and sorting.

The exact mechanism may vary by service, but consistency should be preferred within a domain.

Idempotency and Retries​

Operations that may be retried—especially those involving transactions or external effects—should be designed to avoid unintended duplication where practical.

Observability​

Services should produce enough operational information to understand failures and performance without exposing sensitive user information.

Useful capabilities may include:

  • Structured logs
  • Metrics
  • Traces
  • Correlation identifiers
  • Service health indicators

Documentation​

Public API documentation should describe only interfaces intended for public or contributor use.

Internal endpoints, environment-specific routes, infrastructure details and privileged operations should remain in controlled documentation.

For contributor projects, API documentation should explain:

  • Purpose
  • Request format
  • Response format
  • Authentication requirements
  • Authorization requirements
  • Error behavior
  • Examples where appropriate

Change Management​

Breaking changes should be intentional, documented and accompanied by a migration path where practical.

Contributors should avoid changing an established contract merely to simplify one implementation.

Interfaces should remain stable even as implementation evolves.