ISSUE-16135: [PIP-178] Support the admin API to check unknown request parameters

[sijie]

Original Issue: apache#16135

---

Motivation

The design of the Admin API is now such that if an incorrect parameter name is submitted, this property (if not required) will be ignored, then execution continues, and the response is “204 Success”. This will trick the user into thinking the setup succeeded when it didn't correctly as expected in some cases, as shown below:

User POST request to /{tenant}/{namespace}/{topic}/retention" with incorrect parameter:

{"retention_size_in_mb":-1,"retention_time_in_minutes":40320}

Which should have been this:

{"retentionSizeInMB":-1,"retentionTimeInMinutes":40320}

Response:

HTTP/1.1 204 No Content
Date: Mon, 20 Jun 2022 02:54:25 GMT
broker-address: 127.0.0.1
Server: Jetty(9.4.44.v20210927)

We can provide an optional mechanism: "fail (HTTP status 400 bad requests) on unknown request parameters".

Goal

• scope:
  • Path variables(no need for change): This represents the domain. The current API has been validated, so no additional modifications are required.
  • Query params(no support on this proposal): I haven't found an elegant way to do it yet, so this proposal does not include Query Param validation.
  • Entity properties: This proposal only handles requests whose Content-type is "application/json" (in fact, this is the only type in our project).
• Configurable(no dynamic), minimum configuration granularity is the admin version(v2, v3)

Approach

When parsing the request body, any unknown property is considered a bad request. The Jackson unknown property rule is adopted:

• Case sensitive.
• Special characters are not ignored.
• Do not trim Spaces.

If the check fails, return a text/plain response with 400 code. Like this:

HTTP/1.1 400 Bad Request
Date: Mon, 20 Jun 2022 03:52:10 GMT
broker-address: 127.0.0.1
Content-Type: text/plain
Content-Length: 432
Server: Jetty(9.4.44.v20210927)

Unrecognized field "retention_size_in_mb" (class org.apache.pulsar.common.policies.data.RetentionPolicies known properties: "retentionSizeInMB", "retentionTimeInMinutes"])

Configuration Changes

broker.conf

# Admin API fail on unknown request parameter in request-body. see PIP-178. Setting this to blank means that this feature is turned off.
adminApiFailOnUnknownProperties=v2,v3