{"slug":"oip-rest","title":"What is REST?","body":"## What this article explains\n\nREST (Representational State of Resource) is a common way to design APIs (Application Programming Interfaces) around resources. A resource is a thing with a URL (Uniform Resource Locator). The method says what kind of action you are taking. API is a set of defined rules that enable different applications to communicate with each other. REST is different from MCP (Model Context Protocol), which is an open standard where an AI model connects to an MCP server over a session and the server exposes tools, resources, and prompts the model can call. In contrast, REST uses plain URLs and does not require a persistent session.\n\n## Plain words\n\n`GET` reads. `POST` creates or runs. `PATCH` changes part of something. `PUT` replaces. `DELETE` removes. The URL names the object. The body carries the input. A server is a computer that provides services or data to other computers. A token is a unique string used for authentication. An endpoint is a URL that an application uses to interact with a server.\n\n## How REST works in this build\n\nThe build uses REST-shaped routes for articles, directory rows, files, tasks, protocol jobs, self-tests, and dispatch. OIP (Object Invocation Protocol) adds the missing piece that normal REST does not always provide: the object explains itself and every action should leave a receipt. This can be achieved by using JSON (JavaScript Object Notation) to define the object and its actions. To invoke an object, you can use the `/api/dispatch` endpoint with a `POST` request, providing the object key and body. The invocation will be recorded in an append-only ledger with a receipt at `/api/dispatch?receipt=inv_ID`. CLI (Command-Line Interface) tools like `curl` can be used to perform these actions.\n\n## Machine shape\n\nA REST action is machine-native when it includes `method`, `url`, `body_schema`, `auth`, `success_shape`, `failure_shape`, and `proof_route`. For more information on MCP, see the [MCP article](/a/mcp). For more information on REST and OIP, see the [OIP REST article](/a/oip-rest).\n\n## Example use case\n\nTo create a new article, you can use the `/api/articles` endpoint with a `POST` request, providing the article title and body. This can be done using `curl` with the following command: `curl -X POST /api/articles -H 'Content-Type: application/json' -d '{\"title\":\"My Article\",\"body\":\"This is my article\"}'`. This will create a new article and return a receipt with the article ID.\n## Latest clarity reviews (live)\n\nFresh 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.\n\n- 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\n  - gaps named: MCP; API; CLI\n- 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\n  - gaps named: MCP; API; CLI\n\nHow 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.","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"}}