API Architecture — Proposed Guide

API Architecture: The proposed architecture uses resource-oriented HTTP contracts with a separate event channel for changes. A synchronous response would…

Overview

The proposed architecture uses resource-oriented HTTP contracts with a separate event channel for changes. A synchronous response would describe one operation; an event would describe a fact that has already occurred.

Key concepts

Keep authorization, validation and state-transition checks at the service boundary. Use stable resource identifiers rather than labels that a user can rename.

Implementation considerations

Document transactional boundaries before allowing operations that touch several resources. This architecture is a design proposal, not a description of deployed Remizen services.

Illustrative data model

This local fixture shows a possible representation for the concepts above. It is not an endpoint response, production configuration or a claim that the described capability is implemented.

{
  "reference_only": true,
  "topic": "API Architecture",
  "resource_type": "expense",
  "resource_id": "resource_example_123",
  "version": 1,
  "event_type": "expense.updated"
}

Design review checklist

• Document which organization owns the api architecture representation and which actor may view or change it.
• Test the boundaries of resource type, resource id, version, event type using synthetic values, including missing or inconsistent references.
• Before future implementation, obtain an approved contract and review failure behavior. This documentation does not authorize production activation.

Proposed data types

Related documentation