Skip to content

API Model

This document defines the API model used by WildEditorInChief (WEIC).

The API model describes the resource types, endpoint patterns, read and write behavior, and security expectations that expose the WEIC knowledge platform to clients.

WEIC is designed as an API-first system. Document, fragment, revision, and tagging operations occur through the API layer rather than through direct database access or tightly coupled client logic.

Purpose

The API model exists to support several goals:

  • expose WEIC content and metadata through stable resource patterns
  • separate client behavior from storage implementation details
  • support multiple clients against the same business logic
  • preserve revision-first behavior at the service boundary
  • provide a secure and governable interface for document operations

This model connects the WEIC storage design to the running platform.

API-first principle

WEIC uses an API-first design.

This means:

  • clients interact with documents, fragments, and metadata through HTTP APIs
  • storage details remain behind the service boundary
  • validation and authorization occur in the application layer
  • business rules are centralized rather than duplicated across clients

This model supports browser clients, internal tools, automation workflows, and future integrations.

Core resource types

The initial WEIC API model exposes several core resource categories:

  • documents
  • document revisions
  • fragments
  • fragment revisions
  • tags

Future resource categories may include:

  • review records
  • publication records
  • attachments
  • evidence associations

Document resources

Document resources expose stable document identity and metadata.

Typical document operations include:

  • create document
  • get document
  • list documents
  • update document metadata
  • get current revision
  • list revision history
  • create a new revision

Example endpoint layout:

GET    /api/documents
POST   /api/documents
GET    /api/documents/{id}
PATCH  /api/documents/{id}
GET    /api/documents/{id}/revisions
POST   /api/documents/{id}/revisions
GET    /api/documents/{id}/revisions/{revisionId}

Document metadata updates should remain separate from content revision creation.

Fragment resources

Fragment resources expose reusable content units and their revision history.

Typical fragment operations include:

  • create fragment
  • get fragment
  • list fragments
  • update fragment metadata
  • create fragment revision
  • list fragment revisions
  • retrieve a specific fragment revision

Example endpoint layout:

GET    /api/fragments
POST   /api/fragments
GET    /api/fragments/{id}
PATCH  /api/fragments/{id}
GET    /api/fragments/{id}/revisions
POST   /api/fragments/{id}/revisions
GET    /api/fragments/{id}/revisions/{revisionId}

Fragments follow the same revision-first behavior as documents.

Tag resources

Tag resources support document classification and retrieval.

Typical tag operations include:

  • create tag
  • list tags
  • attach tag to document
  • remove tag from document
  • list tags on a document

Example endpoint layout:

GET    /api/tags
POST   /api/tags
GET    /api/documents/{id}/tags
POST   /api/documents/{id}/tags
DELETE /api/documents/{id}/tags/{tagId}

Tag operations should remain simple and reusable.

Read model

The read model should expose current state clearly.

Typical document responses should include:

  • stable document metadata
  • current revision identifier
  • optionally current HTML content where appropriate

Typical fragment responses should include:

  • stable fragment metadata
  • current revision identifier
  • optionally current HTML content where appropriate

Revision history endpoints should expose historical revisions separately from current resource views.

This keeps current state and historical state distinct.

Write model

The write model should preserve revision-first behavior.

Metadata updates

Document or fragment metadata updates should occur through metadata update endpoints such as:

PATCH /api/documents/{id}
PATCH /api/fragments/{id}

These operations may update fields such as:

  • title
  • slug
  • owner
  • status
  • name for fragments

Content updates

Body content changes should create new revisions rather than overwrite current content in place.

Examples:

POST /api/documents/{id}/revisions
POST /api/fragments/{id}/revisions

This preserves history and keeps content state traceable.

Revision behavior

The API should make revision behavior explicit.

This means:

  • creating a revision is a distinct operation
  • revision history is retrievable
  • the current revision is identified by pointer
  • clients should not treat body content as an in-place mutable field

This applies equally to documents and fragments.

Security model at the API layer

WEIC API access is protected through centralized authentication and role-based authorization.

Current security assumptions include:

  • Keycloak authentication
  • JWT bearer tokens
  • role-based access control

Typical roles include:

Role Purpose
reader retrieve documents and metadata
editor create and update documents, fragments, and revisions
administrator manage higher-level governance and administrative operations

Authorization should be enforced in the API layer rather than left to clients.

Validation expectations

The API should validate input before storage operations occur.

Typical validation responsibilities include:

  • required field checks
  • slug and identifier constraints
  • allowed status values
  • valid HTML body input expectations
  • revision note constraints where applicable
  • tag uniqueness rules where applicable

Validation belongs in the application layer so that clients receive clear and predictable errors.

Response principles

API responses should be predictable and structured.

Typical goals include:

  • explicit success and failure results
  • stable resource identifiers
  • separate handling of metadata and revisions
  • clear authorization failures
  • clear validation failures

This makes WEIC easier to build against and easier to govern.

Future extensions

The API model is intentionally focused on the core knowledge layer, but it is designed to support later extensions such as:

  • review workflows
  • publication workflows
  • approval state transitions
  • attachments
  • evidence linking
  • search endpoints

These additions can build on the same resource-oriented API principles.

Relationship to the Oryvin plan

WEIC is the knowledge core of the Oryvin ecosystem. The API model defines how that knowledge is exposed to applications, tools, and future automation.

structured storage
        ↓
WEIC API resources
        ↓
clients, workflows, and future integrations

This is one of the steps that turns WEIC from a storage design into a buildable platform service.