OIP REST Protocol

Introduction

OIP (Object Invocation Protocol) defines a protocol for invoking work objects. An OIP work object is a unit of computation that performs a specific task. OIP ensures every invocation appends to an immutable ledger and produces a receipt, enabling replay and repair.

REST (Representational State Transfer) is an architectural style for distributed hypermedia systems. REST defines a set of constraints for designing Application Programming Interfaces (APIs). An API is a set of defined rules enabling different applications to communicate with each other. REST interactions involve stateless requests and standard HTTP methods operating on resources identified by Uniform Resource Locators (URLs).

MCP (Model Context Protocol) defines a protocol where a model connects to an MCP server over a session. The MCP server exposes tools, resources, and prompts over a session. MCP establishes a persistent session for contextual interactions. REST operates with stateless requests, contrasting with MCP's session-based model property.

JSON (JavaScript Object Notation) is a lightweight data-interchange format. OIP uses JSON for defining object schemas and data payloads.

CLI (Command-Line Interface) refers to a text-based interface for interacting with a computer program. CLI tools perform OIP invocations.

OIP REST Mechanisms

OIP implements REST principles for object invocation and resource management. The OIP unit is the work object. An OIP invocation is a request to a work object to perform a defined action. The /api/dispatch route performs object invocations. A POST request to /api/dispatch with a key and body invokes an object. A GET request to /api/dispatch with invoke=KEY and body parameters also invokes an object. Every invocation appends to an immutable ledger. The OIP proof is the receipt. A receipt is returned at /api/dispatch?receipt=inv_ID upon successful ledger append. The OIP loop defines the lifecycle of an invocation: object, invoke, ledger, receipt, replay, repair.

OIP uses standard HTTP methods: GET retrieves resource state. POST creates a new resource or performs an action. PATCH applies partial modifications to a resource. PUT replaces a resource. DELETE removes a resource. The URL identifies the target object or resource. The request body carries the input parameters for the invocation.

Machine Shape

An OIP REST action is machine-native when it defines the following properties:

{
  "action_properties": {
    "method": { "type": "string", "description": "The HTTP method (e.g., GET, POST)." },
    "url": { "type": "string", "description": "The Uniform Resource Locator (URL) for the action." },
    "body_schema": { "type": "object", "description": "A JSON schema for the request body." },
    "auth": { "type": "object", "description": "Authentication requirements for the action." },
    "success_shape": { "type": "object", "description": "A JSON schema for a successful response." },
    "failure_shape": { "type": "object", "description": "A JSON schema for an error response." },
    "proof_route": { "type": "string", "description": "The URL route for retrieving the invocation receipt." }
  },
  "routes": {
    "/api/dispatch": {
      "description": "The `/api/dispatch` route is the primary OIP endpoint for invoking work objects. It accepts an object key and body parameters.",
      "methods": {
        "POST": {
          "body_schema": {
            "type": "object",
            "properties": {
              "key": { "type": "string", "description": "The unique identifier for the work object to invoke." },
              "body": { "type": "object", "description": "The input parameters for the object invocation." }
            },
            "required": ["key", "body"]
          },
          "proof_route": "/api/dispatch?receipt={inv_ID}"
        },
        "GET": {
          "query_params": {
            "invoke": { "type": "string", "description": "The unique identifier for the work object to invoke." },
            "body": { "type": "string", "description": "JSON string of input parameters for the object invocation." }
          },
          "proof_route": "/api/dispatch?receipt={inv_ID}"
        }
      }
    },
    "/api/articles": {
      "description": "The `/api/articles` route manages OIP documentation articles. A `POST` invocation creates a new article.",
      "methods": {
        "POST": {
          "body_schema": {
            "type": "object",
            "properties": {
              "title": { "type": "string", "description": "The title of the new article." },
              "body": { "type": "string", "description": "The markdown content of the new article." }
            },
            "required": ["title", "body"]
          },
          "proof_route": "/api/dispatch?receipt={inv_ID}"
        }
      }
    },
    "/a/{slug}": {
      "description": "The `/a/{slug}` route retrieves a specific OIP documentation article by its slug identifier.",
      "methods": {
        "GET": {
          "params": {
            "slug": { "type": "string", "description": "The unique identifier (slug) of the article." }
          }
        }
      }
    },
    "/a/mcp": {
      "description": "The `/a/mcp` route retrieves the Model Context Protocol (MCP) documentation article.",
      "methods": {
        "GET": {}
      }
    }
  }
}

Example Use Case

To create a new article, an OIP client performs a POST invocation to the /api/articles route. The request body provides the article title and body as JSON. This invocation appends to the ledger and returns a receipt. A CLI tool performs this action with the following command:

curl -X POST /api/articles \
  -H 'Content-Type: application/json' \
  -d '{"title":"OIP REST Example Article","body":"This article demonstrates OIP REST principles."}'

The server returns a receipt identifier, inv_ID, which proves the article creation invocation. The receipt is retrievable at /api/dispatch?receipt=inv_ID.

Receipt Rule

An OIP receipt proves the successful invocation of a work object via a defined route. The receipt contains the invocation ID, the invoked object's key, the input parameters, the timestamp, and a cryptographic signature. The receipt confirms the invocation's append to the immutable ledger.

Conformance Rule

An OIP implementation conforms to the REST protocol specification when it processes invocations via defined REST routes, appends every invocation to an immutable ledger, and returns a verifiable receipt at /api/dispatch?receipt=inv_ID for each successful invocation. Conformant behavior includes adherence to specified HTTP methods, URL structures, and JSON schemas for requests and responses.

Latest clarity reviews (live)

Fresh models are sent this article's bundle and asked two separate questions: how clear is the machine JSON, and how clear is the English body. Scores are 0 to 10. The full history is in the append-only ledger.

• 2026-07-03 03:02 · model @cf/meta/llama-3.3-70b-instruct-fp8-fast · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 6/10

- gaps named: MCP; API; CLI

• 2026-07-02 23:37 · model @cf/meta/llama-3.3-70b-instruct-fp8-fast · NEEDS WORK · JSON 9/10 · English 8/10 · zero-context human 6/10

- gaps named: MCP; API; CLI

How the loop self-corrects: a failing review queues a model revision of this article (a new append-only version). A missing concept named by a reviewer queues a brand-new machine-written article, which then enters the same review cycle.