Honor methods property for entities backed by tables/views

[cbunyard]

Why make this change?

Closes #1771

Currently, the methods property in REST configuration only applies to stored procedures. For tables and views, all 5 HTTP verbs (GET, POST, PUT, PATCH, DELETE) are always exposed in the OpenAPI document and allowed at runtime, regardless of the methods configuration. This creates a mismatch between the API contract (OpenAPI) and the intended API surface.

Users need the ability to expose read-only REST APIs for views/tables used in reporting and analytics scenarios, and to generate clean OpenAPI documents for API Management (APIM) integration. This change extends methods filtering to tables and views, making the configuration work consistently across all entity types.

What is this change?

This change extends the REST methods configuration property to work with tables and views, not just stored procedures. Previously, configuring methods on tables/views was ignored - all 5 HTTP verbs were always exposed in the OpenAPI document and allowed at runtime.

The implementation includes:

• Runtime method enforcement - Validates configured methods before authorization checks, returning 405 Method Not Allowed for disallowed operations (consistent with stored procedure behavior)
• OpenAPI filtering - Generates OpenAPI documents that only include configured operations, and conditionally generates request schemas based on which methods are enabled (_NoAutoPK for POST, _NoPK for PUT/PATCH)
• CLI support - Removes validation that prevented --rest.methods from being used with tables/views, and updates help text to reflect support for all entity types
• Configuration updates - Removes obsolete validation warnings and updates documentation to indicate that methods applies to all entity types

Key design decisions:

• Empty methods array or null/undefined values continue to allow all 5 HTTP verbs (backward compatible default behavior)
• Method enforcement occurs before authorization checks, matching stored procedure behavior
• Zero impact on GraphQL endpoints, which use separate configuration

How was this tested?

• Integration Tests
• Unit Tests

New Test Files:

• src/Service.Tests/RestApiTests/MethodEnforcementTests.cs - Runtime method enforcement for tables/views
• src/Service.Tests/OpenApiDocumentor/MethodFilteringTests.cs - OpenAPI operation filtering

Modified Test Files:

• src/Service.Tests/OpenApiDocumentor/PathValidationTests.cs - Verify filtered operations in OpenAPI document
• src/Service.Tests/OpenApiDocumentor/DocumentVerbosityTests.cs - Verify schema pruning
• src/Service.Tests/Configuration/ConfigurationTests.cs - Existing stored procedure tests continue to pass

[Copilot]

Pull Request Overview

This PR extends REST method filtering configuration to work with tables and views, not just stored procedures. Previously, the methods property was ignored for tables/views, always exposing all 5 HTTP verbs regardless of configuration. This change enables read-only REST APIs and generates clean OpenAPI documents that only include configured operations.

Key changes include:

• Runtime method enforcement before authorization checks for all entity types
• OpenAPI document filtering to only include configured operations and conditionally generate request schemas
• CLI support for --rest.methods with tables/views and updated help text

Reviewed Changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/Service.Tests/dab-config.MsSql.json	Adds test entity configurations for read-only, write-only, and partial CRUD scenarios
src/Service.Tests/SqlTests/RestApiTests/MethodEnforcementTests.cs	New integration tests for runtime method enforcement on tables/views
src/Service.Tests/OpenApiDocumentor/SchemaGenerationTests.cs	New tests validating conditional schema generation based on configured methods
src/Service.Tests/OpenApiDocumentor/PathValidationTests.cs	Updated tests to verify filtered operations in OpenAPI documents
src/Service.Tests/OpenApiDocumentor/MethodFilteringTests.cs	New unit tests for the GetConfiguredRestOperations method behavior
src/Service.Tests/Configuration/ConfigurationTests.cs	Adds test for custom OpenAPI description configuration
src/Core/Services/RestService.cs	Updates method enforcement to apply to all entity types, not just stored procedures
src/Core/Services/OpenAPI/OpenApiDocumentor.cs	Implements operation filtering and conditional schema generation for OpenAPI documents
src/Core/Configurations/RuntimeConfigValidator.cs	Removes obsolete validation that prevented methods configuration on tables/views
src/Config/ObjectModel/RuntimeOptions.cs	Adds OpenApiDescription property to runtime configuration
src/Config/ObjectModel/RuntimeConfig.cs	Exposes OpenApiDescription through runtime config
src/Cli/ConfigGenerator.cs	Updates CLI to support REST methods for all entity types
src/Cli/Commands/InitOptions.cs	Adds OpenApiDescription option to init command
src/Cli/Commands/EntityOptions.cs	Updates help text to indicate methods apply to all entity types
src/Cli/Commands/ConfigureOptions.cs	Adds OpenApiDescription option to configure command
src/Cli.Tests/InitTests.cs	Tests OpenApiDescription configuration during init
src/Cli.Tests/ConfigureOptionsTests.cs	Tests OpenApiDescription configuration during update
schemas/dab.draft.schema.json	Adds schema definition for openapi-description property
docs/fork-management-guide.md	New documentation for maintaining custom features while tracking upstream
README.md	Adds example of openapi-description in configuration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[JerryNixon]

First, thank you for your contribution.

A request before future pull requests

I really wish we could have discussed this proposal before you opened the PR. It would have saved some effort and clarified direction early. Let’s walk through what’s happening here.

The current behavior

As described in #1771, Data API builder supports read-only REST operations today by restricting the actions in permissions to only read.

Example:

{
  "entities": {
    "book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [ "read" ] // read-only for anonymous
        }
      ]
    }
  }
}

Even in this simple case, the OpenAPI output still lists all HTTP methods, which is incorrect.

Now consider a second role:

{
  "entities": {
    "book": {
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] },
        { "role": "authorized", "actions": [ "create", "read", "update" ] }
      ]
    }
  }
}

Again, the OpenAPI output still includes every REST method, ignoring that anonymous can only read and authorized can create or update.

And if we add a third role:

{
  "entities": {
    "book": {
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] },
        { "role": "authorized", "actions": [ "create", "read", "update" ] },
        { "role": "administrator", "actions": [ "create", "read", "update", "delete" ] }
      ]
    }
  }
}

The OpenAPI document still shows all methods. That’s the core problem: the available REST methods depend on the user’s role, yet the OpenAPI document ignores this and presents them all.

Why the proposed rest.method approach does not work

A developer could not configure dab-config.json to accurately describe these role-based variations using your proposed rest.method property.

rest.method is not tied to role, which would create two issues:

1. A mismatch between permissions.actions and the REST methods shown in OpenAPI.
2. Duplication of configuration, repeating the same logic already defined in permissions.

This makes it impossible to align configuration with actual runtime behavior.

Where we are

• [Cancelled]: Role-specific OpenAPI & GraphQL Schema support #2368 will allow generation of a role-specific OpenAPI document, so the spec matches the active user role.
• [Enh]: OpenAPI REST methods should show only available methods #2946 will complete the picture by deriving available REST methods from permissions.actions for that role.

Together, these solve the entire mismatch.

Next steps

The correct direction is described in #2276. That work will unify OpenAPI generation with role-based permissions and eliminate the need for the rest.method property to be modified in any way.

[cbunyard]

Closed pending a future conversation.