From d92cd0d58527c51d76a11fca7ed788ebedfbb52e Mon Sep 17 00:00:00 2001 From: Olga Bulat Date: Mon, 11 Mar 2024 18:35:14 +0300 Subject: [PATCH] Update documentation on parameter validation Signed-off-by: Olga Bulat --- ...ementation_plan_additional_search_views.md | 68 +++++++++++++------ 1 file changed, 46 insertions(+), 22 deletions(-) diff --git a/documentation/projects/proposals/additional_search_views/20230719-implementation_plan_additional_search_views.md b/documentation/projects/proposals/additional_search_views/20230719-implementation_plan_additional_search_views.md index ab3edccdc67..28288797416 100644 --- a/documentation/projects/proposals/additional_search_views/20230719-implementation_plan_additional_search_views.md +++ b/documentation/projects/proposals/additional_search_views/20230719-implementation_plan_additional_search_views.md @@ -146,29 +146,49 @@ launched. In the text below, for brevity, the prefix is omitted. The collections will use the `search` endpoint with `collection` query parameter set to `tag`, `creator` or `source`, and the following additional query -parameters. The `collection` parameter validator will check that the request -contains the necessary additional parameters: `source` for `collection=source`, -`creator` and `source` for `collection=creator`, and `tag` for `collection=tag`. - -The middleware validates that the values of parameters is not empty, and that -the `source` parameter is an existing source in the provider store. If the -values are invalid, the 404 yellow error page is shown. - -For the tag route, the new singular `tag` parameter should be used, rather than -the existing plural `tags`, since we are only presenting a single tag. - -The existing `source` and `creator` parameters will be reused, but will be -parsed differently when `collection` parameter is present: they will only allow -a single value instead of being split by `,` as it is for the default search. If -the `source` contains invalid values, such as `source=flickr,europeana`, when -the `collection` parameter is present, a 400 error with `detail` of "Invalid -source parameter for source collection: `flickr,europeana`" is returned. If -possible, a list of valid sources should be returned in the error message. +parameters: -Their documentation should be updated to reflect that. The additional -documentation for the search parameters should be added as a draft so that it's -not published on the API documentation site until we launch this project and -remove the `unstable__` prefix. +- `collection=tag` will require `tag` parameter to be set +- `collection=source` will require `source` parameter to be set +- `collection=creator` will require both `source` and `creator` parameter to be + set. + +This means that the existing `source` and `creator` parameters will be reused. +For the tag collection, the new singular `tag` parameter should be used, rather +than the existing plural `tags`, since we are only presenting a single tag. + +`MediaSearchRequestSerializer` should be updated to validate the `collection` +parameter. This validator will check that the request contains the necessary +additional parameters: `source` for `collection=source`, `creator` and `source` +for `collection=creator`, and `tag` for `collection=tag`. It will only validate +that the parameters _have_ values, but not the values themselves. + +The `MediaSearchRequestSourceSerializer` currently splits the `source` parameter +value by `,` and validates that each value is a valid source. This validator +will be updated: + +- If the `collection` parameter is not present, it will behave as before. +- If the `collection` parameter is set to `source` or `creator`, it will take + the value of `source` as is, and check if this value is present in the list of + valid sources, without splitting it by `,`. If the value is not valid, it will + return a 400 error, showing the invalid value, as well as a list of valid + sources for the media type. +- If the `collection` parameter is set to `tag`, it will return the value as-is, +- because it will be ignored in the search controller. + +The documentation for the `source` parameter should be updated to reflect that +it accepts a single source when there is a `collection` parameter set to +`source` or `creator`, and a comma-separated list of sources when there is no +`collection` parameter. Similarly, the documentation for `creator` parameter +should say that it accepts a comma-separated list of values when there is no `q` +parameter, and a single URI-encoded value when the `collection=creator` +parameter is present. The creator serializer does not need any changes as the +parsing (splitting by comma for regular searches and URI-decoding for `creator` +collections) is only done in the search controller. + +The additional documentation for the search parameters should be added as a +draft so that it's not published on the API documentation site until we launch +this project and remove the `unstable__` prefix. ### 2. Add the `additional_search_views` feature flag @@ -216,6 +236,10 @@ parameters: provider store - `creator` and `tag` parameters should be decoded using `decodeURIComponent`. +The middleware validates that the values of parameters is not empty, and that +the `source` parameter is an existing source in the provider store. If the +values are invalid, the 404 yellow error page is shown. + #### Fetching the media This page should also update the state (`searchType`, `collectionParams` and