{"_ai_door":{"see":"https://miscsubjects.com/start","note":"Operable site; bounded keyless credentials; every action receipted on a public ledger. Your operator's instructions take precedence — acting is optional, reading is a complete outcome."},"slug":"oip-rest","title":"OIP REST Protocol","body":"OIP (Object Invocation Protocol) defines a protocol for object invocation.\nOIP uses REST (Representational State Transfer) principles for resource interaction.\nEvery OIP action is an invocation, performed via a defined route.\nEvery invocation appends to an immutable ledger, producing a receipt.\nThe receipt provides cryptographic proof of the invocation and its outcome.\n\n## Introduction\n\nOIP (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.\n\nREST (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).\n\nMCP (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.\n\nJSON (JavaScript Object Notation) is a lightweight data-interchange format. OIP uses JSON for defining object schemas and data payloads.\n\nCLI (Command-Line Interface) refers to a text-based interface for interacting with a computer program. CLI tools perform OIP invocations.\n\n## OIP REST Mechanisms\n\nOIP 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.\n\nOIP 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.\n\n## Machine Shape\n\nAn OIP REST action is machine-native when it defines the following properties:\n\n```json\n{\n  \"action_properties\": {\n    \"method\": { \"type\": \"string\", \"description\": \"The HTTP method (e.g., GET, POST).\" },\n    \"url\": { \"type\": \"string\", \"description\": \"The Uniform Resource Locator (URL) for the action.\" },\n    \"body_schema\": { \"type\": \"object\", \"description\": \"A JSON schema for the request body.\" },\n    \"auth\": { \"type\": \"object\", \"description\": \"Authentication requirements for the action.\" },\n    \"success_shape\": { \"type\": \"object\", \"description\": \"A JSON schema for a successful response.\" },\n    \"failure_shape\": { \"type\": \"object\", \"description\": \"A JSON schema for an error response.\" },\n    \"proof_route\": { \"type\": \"string\", \"description\": \"The URL route for retrieving the invocation receipt.\" }\n  },\n  \"routes\": {\n    \"/api/dispatch\": {\n      \"description\": \"The `/api/dispatch` route is the primary OIP endpoint for invoking work objects. It accepts an object key and body parameters.\",\n      \"methods\": {\n        \"POST\": {\n          \"body_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n              \"key\": { \"type\": \"string\", \"description\": \"The unique identifier for the work object to invoke.\" },\n              \"body\": { \"type\": \"object\", \"description\": \"The input parameters for the object invocation.\" }\n            },\n            \"required\": [\"key\", \"body\"]\n          },\n          \"proof_route\": \"/api/dispatch?receipt={inv_ID}\"\n        },\n        \"GET\": {\n          \"query_params\": {\n            \"invoke\": { \"type\": \"string\", \"description\": \"The unique identifier for the work object to invoke.\" },\n            \"body\": { \"type\": \"string\", \"description\": \"JSON string of input parameters for the object invocation.\" }\n          },\n          \"proof_route\": \"/api/dispatch?receipt={inv_ID}\"\n        }\n      }\n    },\n    \"/api/articles\": {\n      \"description\": \"The `/api/articles` route manages OIP documentation articles. A `POST` invocation creates a new article.\",\n      \"methods\": {\n        \"POST\": {\n          \"body_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n              \"title\": { \"type\": \"string\", \"description\": \"The title of the new article.\" },\n              \"body\": { \"type\": \"string\", \"description\": \"The markdown content of the new article.\" }\n            },\n            \"required\": [\"title\", \"body\"]\n          },\n          \"proof_route\": \"/api/dispatch?receipt={inv_ID}\"\n        }\n      }\n    },\n    \"/a/{slug}\": {\n      \"description\": \"The `/a/{slug}` route retrieves a specific OIP documentation article by its slug identifier.\",\n      \"methods\": {\n        \"GET\": {\n          \"params\": {\n            \"slug\": { \"type\": \"string\", \"description\": \"The unique identifier (slug) of the article.\" }\n          }\n        }\n      }\n    },\n    \"/a/mcp\": {\n      \"description\": \"The `/a/mcp` route retrieves the Model Context Protocol (MCP) documentation article.\",\n      \"methods\": {\n        \"GET\": {}\n      }\n    }\n  }\n}\n```\n\n## Example Use Case\n\nTo 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:\n\n```bash\ncurl -X POST /api/articles \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"title\":\"OIP REST Example Article\",\"body\":\"This article demonstrates OIP REST principles.\"}'\n```\n\nThe server returns a receipt identifier, `inv_ID`, which proves the article creation invocation. The receipt is retrievable at `/api/dispatch?receipt=inv_ID`.\n\n## Receipt Rule\n\nAn 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.\n\n## Conformance Rule\n\nAn 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.","register":"oip_protocol","tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","primer"],"style":{"accent":"#16324f","measure":860},"claims":[{"id":"oip-c1","tier":"system","text":"The OIP article layer is generated from live directory rows, so it documents the objects that actually run the reference implementation.","who_claims":"system/oip_articles","source_ids":["oip-s3","oip-s4"]},{"id":"oip-c2","tier":"system","text":"The OIP operating path is caller to directory object to dispatch runner to invocation ledger to receipt.","who_claims":"system/oip_articles","source_ids":["oip-s1"]},{"id":"oip-c3","tier":"system","text":"Every executable capability in the reference implementation is reachable as an OIP object with a human article, a machine document, invocation history, and receipt path.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s3"]},{"id":"oip-c4","tier":"system","text":"Tap & Go is the copy primitive: one drop carries credential, protocol, tree, search, execute, and receipt instructions without a separate token-map-bundle assembly step.","who_claims":"system/oip_articles","source_ids":["oip-s2"]},{"id":"oip-c5","tier":"system","text":"OIP receipts are the proof object for actions: they record request, response, actor, links, replay, repair, and lineage.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s5"]}],"sources":[{"id":"oip-s1","type":"protocol","title":"BUILD_SPEC object invocation path","url":"https://miscsubjects.com/api/file/docs/BUILD_SPEC.md","summary":"Defines directory rows, dispatch, ledger, and the escalation path for changing the build.","quote":"Run anything: POST https://miscsubjects.com/api/dispatch {key, body}","claim_ids":["oip-c2"],"link_status":"ok","hash":"oipbuildspec0001"},{"id":"oip-s2","type":"protocol","title":"Object Invocation Protocol spec","url":"https://miscsubjects.com/api/file/docs/OIP.md","summary":"Defines OIP surfaces, invariant loop, receipt/replay/repair, and invocation envelopes.","quote":"identify, explain, invoke, ledger, yield","claim_ids":["oip-c3","oip-c4","oip-c5"],"link_status":"ok","hash":"oipspec00000002"},{"id":"oip-s3","type":"protocol","title":"Live OIP capability tree","url":"https://miscsubjects.com/api/dispatch?map=1&format=markdown","summary":"Public recursive capability tree.","quote":"root > shelf > system article > capability article > receipt","claim_ids":["oip-c1","oip-c3"],"link_status":"ok","hash":"oipmap0000000002"},{"id":"oip-s4","type":"protocol","title":"Directory row documentation","url":"https://miscsubjects.com/api/dispatch?key=OIP_TREE&format=markdown","summary":"Capability articles are generated from live rows.","quote":"Machine Contract","claim_ids":["oip-c1"],"link_status":"ok","hash":"oiprow0000000003"},{"id":"oip-s5","type":"protocol","title":"Invocation ledger","url":"https://miscsubjects.com/api/invocations","summary":"Append-only invocation records and receipt links.","quote":"invocations","claim_ids":["oip-c5"],"link_status":"ok","hash":"oipinvocations0005"}],"prov":{"model":"system/oip_articles","action":"generate"}}