aboutsummaryrefslogtreecommitdiffstats
path: root/includes/Rest/Handler.php
Commit message (Collapse)AuthorAgeFilesLines
* REST: Make OpenAPI spec info strings translatablebpirkle2025-03-211-70/+28
| | | | | | | | | OpenAPI specs include an "info" section that includes strings such as "title" and "description" that are intended to be human-readable. Make all such strings translatable. Bug: T385855 Change-Id: I15285be6d196c0e7fd7e922f23058d7c09b6b31a
* REST: include ETag in 304 responsesdaniel2025-02-051-0/+1
| | | | | | | | | | | | | | | Why: RFC9110 requires 304 "not modified" responses to contain the "date" and "etag" headers. Failing to include them caused etags to be missing from responses that were returned from cache after checking the backend using if-modified-since. What: - Make Handler::checkPreconditions() call applyConditionalResponseHeaders() to add the conditional headers if the precondition check fails. Bug: T357603 Change-Id: Ic2e288c971774a561395b3df04bab7256ca62014
* Allow translation of nested response body descriptionsfrankie2025-01-301-8/+12
| | | | | | | Extend translation functionality to translate nested parameter properties. Bug: T383790 Change-Id: I22e95764971a4d886136d227016ce36192b41b7f
* Remove 2-line PHPDocs that just repeat the types from the codethiemowmde2025-01-171-19/+0
| | | | | | | | | | | | | | | | Same as Ia294bf4 did for 1-line comments. This patch removes slightly more complex 2-line PHPDoc comments that don't add any new information to the code, but literally repeat what the code already says. They say "don't document the code, code the documentation", and we are doing this more and more. We just tend to forget to remove the obsolete comments. Note I'm also removing a line of text in a few cases when it's very short and literally says the same as the method name. Again, such comments add zero new information. Change-Id: I01535404bab458c6c47e48e5456403b7a64198ed
* REST: Allow response body properties to have translatable descriptionsbpirkle2024-12-171-14/+50
| | | | | | | | | | | | | In https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1078506 we added the ability to specify path/query parameter descriptions as MessageValue objects to expose them in a translatable way in OpenAPI specs. Make the same possible for response body parameters. Caveat: only schema and top-level property descriptions are translated. Description translation in nested objects is not supported in this patch. Bug: T379706 Change-Id: I68215ad55f2e8b2fec4315516e874192faba6595
* REST: Allow request body parameters to have translatable descriptionsbpirkle2024-11-181-9/+29
| | | | | | | | | | | In https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1078506 we added the ability to specify path/query parameter descriptions as MessageValue objects to expose them in a translatable way in OpenAPI specs. Make the same possible for request body parameters, which previously did not expose descriptions. Bug: T378375 Change-Id: Idd1ff0cc12129c50355186d9c1c0f50266a227f7
* REST: make http method available during response schema generationbpirkle2024-10-241-6/+14
| | | | | | | | | | A previous change made it possible to include response schemas in generated OpenAPI specs. However, it did not provide the http method to the code that generates/includes these schemas. Because some handlers support multiple http methods, this is necessary. So add it. Bug: T375530 Change-Id: Ie681d576cdffc387d78a1686e058903761b749ac
* Merge "REST: Allow specifying param descriptions as MessageValue objects"jenkins-bot2024-10-151-0/+10
|\
| * REST: Allow specifying param descriptions as MessageValue objectsbpirkle2024-10-081-0/+10
| | | | | | | | | | | | | | | | | | | | | | | | | | 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
* | REST: Allow specifying response body schemas in json filesbpirkle2024-10-101-0/+17
|/ | | | | | | | | | | | 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
* Switch over a bunch of class_alias uses to actualsJames D. Forrester2024-10-031-1/+1
| | | | Change-Id: Id175a83e71cc910eaee5d5890a9106872a3ca3b8
* Merge "API: clarify the meaning of write access"jenkins-bot2024-08-201-6/+15
|\
| * API: clarify the meaning of write accessdaniel2024-08-131-6/+15
| | | | | | | | | | | | | | | | | | 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
* | Hard-deprecate getBodyValidatorTranslation updater bot2024-07-161-9/+22
|/ | | | | | | | | | | 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
* Merge "REST: Generate request body specs from param settings."jenkins-bot2024-07-101-36/+96
|\
| * REST: Generate request body specs from param settings.daniel2024-07-101-36/+96
| | | | | | | | | | Bug: T323786 Change-Id: I49da2a07efa32759480070c9d93c31d46f211d26
* | param-settings: Remove backward compatibility code from defaultAtieno2024-07-101-15/+5
|/ | | | | | | We no longer have to check for 'body' PARAM_SOURCE from within getParamSettings Bug: T367394 Change-Id: I16075fde2db6ea47f61d1d2df1e07a4ef46b537b
* Normalise string params in MW Rest APIWendy Quarshie2024-07-081-3/+12
| | | | | Bug: T340185 Change-Id: I1b7189d5951dea019897955f8f9749afcc325fe0
* REST: detect mismatching value types in json requestdaniel2024-06-281-1/+9
| | | | | | | | | | | | | | | | | | | | | | | | 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
* REST: Allow other json request typesJakob Warkotsch2024-06-261-0/+5
| | | | | | | | | 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
* REST: Deprecate using "post" as the parameter sourcedaniel2024-06-251-6/+7
| | | | | | | | | | | | | | | | | | 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
* REST: Make module definition files more like OpenAPI specsdaniel2024-06-241-11/+12
| | | | | | | | | | | | | | | | | | | | | | | | 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
* Adjust comments referring to Handler::init(), which no longer existsbpirkle2024-05-221-10/+9
| | | | Change-Id: Iec50e276275935d3d8d1b7156b482738dd215d5c
* REST: introduce getSupportedRequestTypes()daniel2024-05-151-13/+70
| | | | | | | | | | | 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
* Tweak docs stating that time values can be booleansBartosz Dziewoński2024-05-111-1/+1
| | | | | | I just don't see how that could be correct. Change-Id: I193d2df26db401b33bcc9e6a82f3842ff5b8b56e
* Introduce Modules into the REST frameworkdaniel2024-05-081-24/+159
| | | | | | | 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
* Merge "REST: introduce getBodyParamSettings"jenkins-bot2024-05-071-7/+36
|\
| * REST: introduce getBodyParamSettingsdaniel2024-05-071-7/+36
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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
* | Replace all instances of "per default" with "by default"Tim Starling2024-04-291-6/+6
|/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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
* Merge "Disallow optional or empty path parameters"jenkins-bot2024-04-251-0/+7
|\
| * Disallow optional or empty path parametersbpirkle2024-04-241-0/+7
| | | | | | | | | | | | | | | | | | | | 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
* | Comment typo fixesbpirkle2024-04-241-2/+2
| | | | | | | | | | | | | | | | 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
* | REST: skip unused path params when generating OpenAPI specsdaniel2024-04-241-4/+45
|/ | | | | | | | | | | | | | | | | | 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
* Typo fixesfrankie2024-04-231-1/+1
| | | | | | | Two small typo fixes for dev environment and gerrit setup. Bug: T362742 Change-Id: I92399002019a8df51731f8c927ca606f91211b51
* Merge "REST: Improve documentation of methods related to body parsing"jenkins-bot2024-04-051-3/+30
|\
| * REST: Improve documentation of methods related to body parsingdaniel2024-03-291-3/+30
| | | | | | | | | | | | | | This adds contracts for the new methods added for handling body parsing. Bug: T357025 Change-Id: I113454b6f81e3d51893f5b96889ddd4d67923141
* | REST: detect extraneous body fieldsdaniel2024-03-301-0/+28
|/ | | | | | | Throw if a client sends unexpected body fields to a handler that supports body validation. Bug: T360434 Change-Id: I7b8ed5fe23613183f941ab3b162e0a3c488167df
* Merge "REST: Wrap parameter validation errors for the request body"jenkins-bot2024-03-281-12/+8
|\
| * REST: Wrap parameter validation errors for the request bodydaniel2024-03-281-12/+8
| | | | | | | | | | | | | | | | | | | | 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
* | Merge "handler: Declare known sources in Validator"jenkins-bot2024-03-281-0/+5
|\ \ | |/ |/|
| * handler: Declare known sources in ValidatorAtieno2024-03-281-0/+5
| | | | | | | | | | Bug: T358558 Change-Id: I0536e0d659b53c8f85bf7685beffbb5c5d027998
* | REST: Accept POST with empty body and no content-typedaniel2024-03-141-0/+6
|/ | | | | | | | | | | | 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
* Rest: make getValidatedBody return body parametersWendy Quarshie2024-03-131-2/+17
| | | | | Bug: T358850 Change-Id: Icf11749dcddd11e6a9b68f3795923157a108c107
* Rest: allow Handlers to disable body parsing.daniel2024-03-051-0/+11
| | | | | | | | | | | | 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
* Rest router should provide parsed body data to handler.Wendy Quarshie2024-03-041-1/+2
| | | | | bug: T358557 Change-Id: I41e81f1166a09a4409319cced20a76dc08c6869e
* handler: Throw on unsupported bodyAtieno2024-02-291-1/+4
| | | | | Bug: T358557 Change-Id: I62c429521cce24303fa91c3a2e47db77f912b967
* RequestInterface: add getParsedBody and setParsedBody.Wendy Quarshie2024-02-271-0/+25
| | | | | | | 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
* Merge "Rest: Fix unspecific type hints in REST handler/validators"jenkins-bot2024-02-161-7/+7
|\
| * Rest: Fix unspecific type hints in REST handler/validatorsthiemowmde2024-02-161-7/+7
| | | | | | | | Change-Id: I1b002b4dbd4a8ca90aad977029dcc97e5b3fe766
* | Re-apply "REST: Emit swagger spec"Daniel Kinzler2023-12-061-6/+140
| | | | | | | | | | | | | | | | | | This reverts commit 890558f1fa526550128bbfadcef94d72c430d717. This restores Id584208d9b67d877606a0add1d71c9b1784cdb1b with some fixes. Bug: T323786 Bug: T352742 Change-Id: Ib31c451ddd75b06c95a544c8a3d2a64b32264126
generated by cgit v1.2.3 (git 2.25.1) at 2025-04-24 12:19:45 +0000