Surface

Surface API lets you describe once what a thing on your site accepts: each value, its type and what it allows. The module builds every way of editing that thing from the one description, so they all accept the same values and refuse the same mistakes.

What one description gives you

• A settings form.
• A tool, when the Tool API module is installed. The command line (drush tool:run), ECA, MCP servers and AI agents can all run it.
• An HTTP API, from the surface_http submodule.
• An OpenAPI document for that API, from the surface_openapi submodule.
• A JSON Schema of the values, which a JavaScript client can draw a form from. An example module shows this with a React page.

Why

Today a form, an HTTP API and a tool each describe the same values in their own code, and the copies can disagree. A value the form refuses can pass through the API. With Surface API there is one description, and validation runs against it wherever the value arrives.

Status

The module is in active development. It has no stable release, and its API can change without a deprecation path. Use it to try the idea, and report what you find in the issue queue.

Requirements

• Drupal 11.3 or 12
• PHP 8.3 or newer
• Tool API, optional, for the tools

Installation

composer config repositories.portable-schema vcs https://github.com/mlander/portable-schema.git
composer require fago/portable-schema:dev-main
composer require drupal/surface:1.0.x-dev
drush pm:install surface

The first two commands are needed until the schema builder the module uses is merged into fago/portable-schema. For the HTTP API and its OpenAPI document, also run drush pm:install surface_http surface_openapi.

Documentation and examples

The docs folder has a short introduction, a walk-through that builds a first resource, and a reference. The modules folder has example modules that apply the pattern to settings pages, placed blocks, content types, field settings and a React client. Every example is experimental.