Service publication and OpenAPI

Documentation status: reference — see Maturity and evidence.

A logiCells API should be a projection of a model capability, not a second manual definition of the business domain.

Publication chain

Concept
  -> published action
  -> service adapter
  -> route / protocol mapping
  -> OpenAPI or other machine-readable contract

A published action defines the business verb and its typed signature. A service adapter then chooses how that capability is exposed.

Published capability example

actions:
  - action:
      name: Verify
      type: ObjectItem
      published: true
      params:
        - Login:
            dataType: String
            paramType: ptIn
        - Password:
            dataType: String
            paramType: ptIn
        - Result:
            dataType: Boolean
            paramType: ptReturn

OpenAPI

When the HTTP service supports machine-readable contract generation, OpenAPI should be derived from the surface that is actually published:

• routes that are actually exposed;
• input parameters;
• return types;
• documented errors;
• security requirements.

Do not manually maintain an OpenAPI contract that can drift from the published model.

Security

published: true does not mean “accessible to everyone.” Publication, authentication, authorization, validation, and visibility are separate layers.

Rules

• name actions with business verbs;
• do not encode GET, POST, RPC, or framework names in action names;
• model long-running operations as processes or jobs;
• version signature changes as contract changes;
• keep private implementation classes and modules out of public documentation.