Every resource has a Request panel that lets you run a call against your own installation and see the result.
Building a request
- Choose the operation: List, Show, Create, Update or Delete.
- Fill in the parameters the panel offers: an
idfor item operations, query parameters for searches, and a JSON body for create and update. Bodies can be edited as fields or as Raw JSON. - Click Send API Request.
The Response panel shows the HTTP status, the time taken, and the JSON body with syntax highlighting.
How requests run
Requests do not leave the server. They are executed through Omeka's API manager in the same way the admin interface itself works, as the user who is logged in. That has three consequences:
- No API key is needed to send requests from the browser.
- Permissions are exactly those of your Omeka role. A request your role cannot make returns a 403.
- Writes are real. A Create makes a resource, an Update changes one and a Delete removes it.
| Operation | HTTP method | What runs |
|---|---|---|
| List | GET on the collection |
search with your query parameters |
| Show | GET on an item |
read |
| Create | POST |
create with the JSON body |
| Update | PUT |
update with the full JSON body |
| Update (partial) | PATCH |
update with only the keys you send |
| Delete | DELETE |
delete |
Use PATCH when you want to change a few keys without resending the whole resource. Note that when patching resource values with Omeka's default collection behaviour, values not included in the body can be removed; check the response.
Error responses
| Status | Meaning |
|---|---|
| 403 | Your role is not allowed to perform the operation. |
| 404 | No resource with that id. |
| 422 | Validation failed. The body includes an errors map from the API's error store. |
| 405 | The method is not supported for the resource. |
| 500 | The adapter threw an unexpected error; the message is in the body. |