Creating a REST API

A complete resource API with list, read, create, update, and delete: proper methods, statuses, validation, and scopes.

This tutorial builds a full REST resource: GET/POST /api/v1/tasks and GET/PUT/DELETE /api/v1/tasks/{guid}. It assumes the quickstart. If you haven't registered an endpoint before, do Build Your First API first.

The Shape of a Resource

Each row is one API block (on_startup_register_uri_get, _post, _put, _delete) feeding one handler function. The same trigger → work → reply shape from Block Templates.

GET /tasks, List with Filters

1. Trigger on_startup_register_uri_get with URI tasks → handler function.
2. Build the query: optional status param from httpconnection_get_params → query_bool_term_fields → query_bool_filter → query_and, with query_sort_field on _meta.created descending.
3. function_search on the tasks storage; respect limit/offset params for pagination.
4. Reply with httpconnection_set_json: code 200, data = the results array.

POST /tasks, Create with Validation

1. Trigger on_startup_register_uri_post with URI tasks.
2. Validate required fields from the request body with condition_not_empty_value per field → branch; on the false path reply 400 with {"error": "title is required"} (see validation template).
3. Map the body to document fields with mutations_set_bp_field_multiple, then function_create_document_from_mutations.
4. Reply 201 with the created document (it now has its _meta.guid).

GET /tasks/{guid}, Read One

1. The URI block exposes the guid as a param; fetch with function_get_document on the tasks storage.
2. On its found condition: reply 200 with the document. Otherwise: reply 404 with {"error": "not found"}. Wire both paths from the success/error pins (see error handling).

PUT and DELETE

• PUT: same fetch-first guard, then function_update_document_mutations with the changed fields. Reply 200 with the updated document; 404 when missing.
• DELETE: soft-delete with function_remove_document (recoverable), or hard-delete with function_delete_document when you mean it. See document lifecycle. Reply 200 with a small confirmation object.

Scopes and Testing

• Scope the collection endpoints with the lock icon: *public for open reads, *loggedin or a custom scope for writes. See Remote Access Control.
• Activate the blueprint, then test every row of the table with curl: commands in API workflows.
• When the endpoint 404s right after activation, it's almost always a scope or an inactive blueprint. See Common Issues.

Next Steps

API Guide Conventions, error codes, and rate limits for your API. Storages The queries and mutations behind every row of the table. Block Templates The endpoint and validation shapes in one view.

Frequently asked

How do I build a CRUD REST API in RUAL?

One API block per operation: GET and POST /api/v1/tasks for list and create, and GET, PUT and DELETE /api/v1/tasks/{guid} for read, update and delete. Each on_startup_register_uri block feeds one handler function that does the work and replies with the right status: 200 for reads, 201 for creates, 404 for unknown guids.

How do I validate the request body in a RUAL API?

Check each required field with its own condition_not_empty_value block into a branch, and reply 400 on the false path before anything is stored. On the success path, map the body to document fields with mutations_set_bp_field_multiple and create the document from those mutations.

Should a RUAL DELETE endpoint remove or delete the document?

Your choice: function_remove_document soft-deletes and stays recoverable, while function_delete_document hard-deletes when you mean it. Reply 200 with a small confirmation object either way.

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem