Recipe

Overview

For: maintainers of a decidim-restfull-* gem (or an external RestFull extension gem) adding HTTP endpoints.

Not for: calling the API from a client app — use Operating the API and ReDoc instead.

Follow this page in order. Open topic pages only when you need a single concern (async, RSwag, serializers, …).

Choose your shape

Shape	When	Template
Serializer-only	Component appears in search/show JSON; no new HTTP routes	decidim-restfull-surveys
Read-only HTTP	GET index/show only	Decidim::RestFull::Routing.read_resources — see Routing
Async CRUD	Mutations return 202 + job poll	Decidim::RestFull::Routing.async_resources + ext.api_job — see Async
Host-app one-off	Tenant-specific API in the host Decidim app	Host app extensions + Boot and extension

External gem checklist

1. Gemspec — depend on decidim-restfull-core and the matching decidim-<feature> gem.
2. ENGINE_ROOT — set in lib/decidim-restfull-<feature>.rb (see RestFull engines).
3. Rails engine — lib/decidim/rest_full/<feature>/engine.rb with initializer before: "rest_full.draw_routes" (and before: "rest_full.scopes" as a safety belt).
4. Extension.register in that initializer:
   • ext.oauth_scopes — only scopes not already in core (:meetings, :debates, … are built-in)
   • ext.permissions
   • ext.routes — use Routing DSL
   • ext.api_job for async mutations
   • ext.rswag_specs + ext.open_api_definitions
5. Controller under app/controllers/decidim/api/rest_full/ — see Controllers.
6. Request spec — see RSwag.
7. Verify (Docker):

   docker compose exec rest_full bash -lc 'cd /home/module && bundle exec rails routes -g rest_full | head'
   docker compose exec rest_full bash -lc 'cd /home/module && RAILS_ENV=test bundle exec rspec <your-spec-path>'

Monorepo-only extras

When adding a gem inside the decidim-restfull/ monorepo, also:

• Register the gem in decidim-restfull/decidim-restfull.gemspec
• Add the gem to gem_spec_paths.rb GEMS
• Gate the feature via the Restfull organization Toggle tab (ModuleAvailability) — do not add process-wide Configuration.enable_*_api
• Add available_permissions in configuration.rb when the feature owns a permission group
• Run ./bin/check in Docker

When something breaks

Symptom	Likely cause	Fix
404 on new path	Routes registered after first draw	Boot and extension — initializer order or append API
Scope missing on token	Scopes registered too late	before: "rest_full.scopes"; see Scopes and permissions
OpenAPI path missing	RSwag glob not registered	ext.rswag_specs + regenerate — Generate clients

See also

• Boot and extension — boot order, Extension.register, append API
• RestFull engines — gem layout
• CONTRIBUTING.md — covenant and ./bin/check