# Expose an operation through an API

Source: https://zotonic.com/docs/2966/expose-an-operation-through-an-api

URI: https://zotonic.com/id/2966

Language: en

Start from the site's existing model API or controller patterns. Specify the method, input fields, response shape, and errors before connecting a browser or external client.

Use a read operation for retrieval and an appropriate write operation for changes. Apply authentication and authorization to each operation. Test malformed input and access denial as well as a successful response.

Keep transport details out of shared domain functions so the same operation can serve a template, event handler, or API safely. See <a href="/id/1831" class="doc-reference doc-reference-module"><code>module#mod_oauth2</code></a>, [Expose data through a model](/id/2960), and [Keep permission checks at the boundary](/id/1536).

The greeting model provides a read-only first check. On the site's hostname, request:

```text
GET /api/model/garden/get/greeting
```

Expect a JSON success response with the greeting as its result. Confirm the HTTP status and response body. Request an unknown path too; the model should return its `unknown_path` error. This uses the public example from the model task, so no token is required for that particular value.

For protected operations, use the authentication mechanism supported by <a href="/id/1875" class="doc-reference doc-reference-controller"><code>controller#controller_api</code></a>, for example an appropriately scoped OAuth token. Authentication identifies the caller; the model still must authorize access. Keep tokens out of URLs and example files. Read the controller reference for response envelopes, HTTP methods and request-body handling before adding writes.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/2966?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/2966?language=en>)
