Wellbit Enterprise API Standards

Principles of Wellbit API Design

All external and inter-service APIs engineered by Wellbit Technologies adhere to strict design principles prioritizing predictability, strong typing, backward compatibility, and developer ergonomics.

HTTP Verbs and Resource Semantics

• GET: Safe, idempotent retrieval of resource representations.
• POST: Non-idempotent creation of new resources or execution of complex business operations.
• PUT: Complete idempotent replacement of an existing resource.
• PATCH: Partial modification of an existing resource using JSON merge patch semantics.
• DELETE: Idempotent removal of a resource.

Standard Response Envelopes

Every JSON API endpoint returns a standardized envelope structure:

{
  "success": true,
  "data": {
    "id": "srv_9824fbc1",
    "status": "ACTIVE",
    "created_at": "2026-03-01T12:00:00Z"
  },
  "meta": {
    "trace_id": "trc_4b1a89f92",
    "duration_ms": 34
  }
}

In the event of an error, endpoints return structured error codes:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The payload failed schema verification.",
    "details": [
      {
        "field": "service_name",
        "issue": "Must be an alphanumeric string between 3 and 64 characters."
      }
    ]
  },
  "meta": {
    "trace_id": "trc_4b1a89f92"
  }
}

Security and Authentication

• All public endpoints require TLS 1.3 encryption.
• Authenticated requests must pass bearer tokens formatted as signed JSON Web Tokens (JWT) containing cryptographic expiration (exp) and issuer (iss) claims.
• Sensitive endpoints require explicit mTLS validation.