Previously, response body schemas could be specified by handlers as
php associative arrays, that were included in the final OpenApi spec.
This mixed the schemas with code, and required developers to deal with
specs in multiple formats. Instead, allow specs to be specified in
JSON format, in separate files. In addition to keeping schemas in JSON,
this gives each schame its own git history.
Bug: T376290
Change-Id: Ic27f422df0ab12a3a0b1cbce79eb0be30f7b7815
Previously, parameter descriptions could only be specified as
strings. We want OpenAPI specs generated from parameter
definitions to be internationalizable, so allow specifying
descriptions as MessageValue objects, which can be translated
using normal MediaWiki mechanisms.
Associated improvements to ResponseFactory.
Bug: T376493
Change-Id: If1cbe4f7bfd5c375e64b802b666c0247d65b1ee0
Improve docs for Handler::needsWriteAccess and ApiBase::isWriteMode()
by explaining the contract in terms of what is observable from the
client. Essentially, no write access is needed if the request is "safe"
in the sense defined by RFC 7231 section 4.2.1.
Change-Id: Ifab56a8d6bea3ad4c5282f30bb4eb8d8f5a719b9
This patch emits deprecation warnings when extensions override
Handler::getBodyValidator() or otherwise use JsonBodyValidator.
Request body validation should be performed based on body parameter
declarations returned from getBodyParamSettings().
Bug: T358560
Depends-On: I8b12c9c9d5a73c620e3c5d035f815d7c951c7b30
Change-Id: I44b3395b8d2489c5e7ec8de0077fd7a7c9f49bfe
DEPLOY: watch the api-warning channel for misbehaving clients.
We are now using TypeDef objects for validating fields in JSON
request bodies. Since TypeDef was designed for use in the action API, it
assumes that all client data is originally supplied as strings. These
strings are parsed and converted to the appropriate type.
But for JSON requests, we don't want that. If a field is defined to be a
boolean, it should be required to be a boolean, not the string "yes" or
"0".
This adds an option to TypeDefs that triggers strict type checks for
booleans and numbers. This option is enabled for all request types other
than form data.
For now, the check does not trigger a validation error. It just logs a
warning. This allows us to assess how often clients would trigger this
kind of error. The warning are logged to the "api-warning" channel.
Bug: T305973
Change-Id: I11e9e37af93bc3b9414eb77095e7cc0ce821a462
This changes parseBodyData() to treat request content types ending in
"+json" just like normal application/json requests in order to support
media types such as application/json-patch+json which is used by the
Wikibase REST API for patch endpoints.
Change-Id: Ic47f8f115ec403cab0a8fdd7d53edcd18d130537
Note that "post" parameters remain accessible through
getValidatedParams(), while "body" parameters have to be
accessed though getValidatedBody().
This adds a number of tests that ensure that this remains to be the case,
while deprecation warnings are triggered when appropriate.
Code search to check that this is unused in prod: https://codesearch.wmcloud.org/things/?q=SOURCE+*%3D%3E+*%27post%27&files=&excludeFiles=&repos=
Previous reverted incarnation of this: Ia0eedb383e69b
Bug: T362850
Bug: T358560
Depends-On: Id94335b3ec8f0549ff7350d31cb7cfee8feaa012
Change-Id: I88accc52c5faab70b453709b02ed88a8af4bc181
This splits RouteFileModule into two classes, ExtraRoutesModule and
SpecBasedModule.
ExtraRoutesModule has no module prefix and supports
only "flat" route definition files and additional routes from
extension.json.
SpecBasedModule represents a single module defined in a definition
file similar to an OpenAPI spec. The idea is that a full OpenAPI spec
can be generated by filling in any missing information based on
information provided by the Handler implementation. In particular, the
definition of parameters and request body schemas will be generated.
A JSON schema for the new file format is added under docs/rest/.
Support for the intermediate format introduced in Iebcde4645d4 is
removed. It was not included in a release and was not being used outside
core tests.
Bug: T366837
Change-Id: I4ce306b0997f80b78a3d901e38bbfa8445bed604
REST handlers should explicitly list content types they support for
request bodies. This is needed for generating OpenAPI specs.
NOTE: this removes default support for form data requests, unless
there are "post" parameters declared. "body" parameters require JSON.
Bug: T362850
Change-Id: I1339b1a1770719bd4a5d4d414a8e55fcbb498ac1
Modules group together endpoints by a shared prefix. The idea is that each module has its own version and can generated self-contained self-documentation. This allows clients to have clear expectations about the endpoints of each module, no matter what wiki they are accessing. So far, each wiki may be exposing a different set of endpoints, with no way to provide a spec that describes that set of endpoints in a way that would be consistent across wikis and stable over time.
Bug: T362480
Change-Id: Iebcde4645d472d27eee5a30adb6eee12cc7d046b
Since we introduced support for the "body" PARAM_SOURCE in
getParamSettings, fields in the request body can be defined in the same
way that path and query parameters are defined. However, body fields are
treated separately by the framework, and the value of body fields are
available through getValidatedBody(), rather than getValidatedParams().
Because of that, it makes sense to have a method that returns the param
settings just for the body fields. This also allows handler classes to
override this method separately to specify body fields. That way, it
also becomes possible to have body fields that have the same name as
other parameters.
Bug: T362850
Change-Id: Ia85bf7e46c949a999052d91f1b0d7d579a880108
According to the dictionary, "per" (or more conventionally "as per")
means "according to". Refer OED "per" sense II.3.a. For example:
"No value was passed, so return null, as per default".
In this sentence, we are not specifying the default, we are referring
to the default. This correct usage of "per default" was used nowhere
in MediaWiki core as far as I can see.
Instead we have "per default" being used to mean "by default", that is,
giving the value to use when no explicit value was specified.
In OED, the phrase "by default" is blessed with its own section just
for computing usage:
"P.1.e. Computing. As an option or setting adopted automatically by a
computer program whenever an alternative is not specified by the user
or programmer. Cf. sense I.7a."
There are highly similar pre-computing usages of the same phrase,
whereas the phrase "per default" is not mentioned.
As a matter of style, I think "per default" should not be used even
when it is strictly correct, since the common incorrect usage makes it
ambiguous and misleading.
Change-Id: Ibcccc65ead864d082677b472b34ff32ff41c60ae
After merging gerrit change 1023933, I realized I missed a couple
of comment typos in code review. Also noticed another in Validator.
So just fixing these up for general tidiness.
Change-Id: I7c40274482136ac78dc8ace5f8a0dffa67e4a9cb
Path parameters cannot be optional in OpenAPI specs: each route has a
fixed set of parameters. But the same REST handler can be used for
multiple routes, with some routes using certain parameters, while others
don't.
So from the handler's perspective, these parameters are optional. That
works fine, until we try to generate an OpenAPI spec from the parameter
definitions that the handler returns from getParamSettings. At that
point, we need to inspect the route that the handler was instantiated
for, to see which parameters are actually used in the path. Any
parameters not used in the path need to be excluded from the generated
spec.
Bug: T359652
Change-Id: I81d2c919c87727614a29f53e1dea498326928ef4
Do not allow optional path parameters or empty path segments
within the path. Handlers may still consider a path parameter
to be non-required. Normally this is when a handler services
multiple routes, and not all routes supply all parameters.
Bug: T359652
Change-Id: I4f82ee2b6ec5b631249d26496688e5f42696c1d0
Throw if a client sends unexpected body fields to a handler that supports body validation.
Bug: T360434
Change-Id: I7b8ed5fe23613183f941ab3b162e0a3c488167df
Since we are now using the parameter validation mechanism also for
fields in the request body, we need to wrap the validation errors to
make clear that the "parameters" are actually fields on the request
body.
Bug: T358850
Change-Id: I02e59a66459e8d88d1c5d0e454da9139ec1b42c6
All POST requests must have a body, even if the body's is
empty, with content-length set to 0. When the body is empty, it should
not be necessary to specify a content-type either.
A typical use case would be some kind of "touch" semantics that would
update a resource's state without needing any additional information
from the client.
Change-Id: I7d20bb6a8c484b9b4725f056342ff8d015a171ac
Handlers should be able to opt out of automatic parsing of JSON body
content. This is inportantr in two cases:
1) The handler wants to process the body as a stream
2) The handler wants to use a custon BodyValidator.
Bug: T357025
Bug: T359149
Change-Id: Iac1ad0b723cbad4c79c7119ab0dca8a08b19fe32
Adding getParsedBody is intended to make it easier for us to implement proper request body validation. Also, it get us closer to PSR-7.
Bug: T357025
Change-Id: Ib36d22f15f9226f1f088e55bb335d05dbb7a0e6a
This reverts commit 890558f1fa.
This restores Id584208d9b67d877606a0add1d71c9b1784cdb1b with some fixes.
Bug: T323786
Bug: T352742
Change-Id: Ib31c451ddd75b06c95a544c8a3d2a64b32264126
This is only enabled in development mode for now.
It's intended as a baseline for further development,
the feature is not ready for production.
Bug: T323786
Change-Id: Id584208d9b67d877606a0add1d71c9b1784cdb1b
Co-authored-by: Atieno <pnjira@wikimedia.org>
d70fbfc691 introduced a new helper
function to Rest handlers that prevent caching the response if it sets
any cookies. However, responses to requests where a cookie-based session
(anonymous user with session cookies or logged-in user) are not safe to
cache at all because the session manager may itself attempt to set
cookies on the response outside of the Rest framework, and the response
contents themselves may depend on user-specific invariants, such as the
user's permissions if the current wiki is private (i.e. restricts the
'read' permission to a subset of user groups). We currently rely on
HeaderCallback to fix the first case for us, and don't cover the second
case, so fix it by explicitly sending Cache-Control: private for Rest
responses for requests with an active cookie-based session.
Bug: T264631
Bug: T285210
Change-Id: I9dec6d4accd5de2bd1bde352d45f82c433913d54
This is a modified version of Ie282bc5b5f5df0bbd6a40c8362ba73fcbbf36c2e
which was reverted in 5c7cca8776.
Bug: T321969
Change-Id: I566d54a473aa51c4cdaada21a49d63c0624aab93
This reverts commit d32c260ed0.
Reason for revert: Timo has reservations, I'll submit an updated version later.
Change-Id: I71d4d61a879fda4dccfc105127446cfedde75a7b
