Refine parameter hoisting note

Author: dsotirho-ucsc

lambdas/service/app.py

@@ -840,16 +840,17 @@ def parameter_hoisting_note(method: str,
                             ) -> str:
     return fd('''
         Any of the query parameters documented below can alternatively be passed
-        as a property of a JSON object in the body of the request. This can be
-        useful in case the value of the `filters` query parameter causes the URL
-        to exceed the maximum length of 8192 characters, resulting in a 413
-        Request Entity Too Large response.
+        as a property of a JSON object in the body of the request. This is
+        referred to as *parameter hoisting* and can be useful in case the value
+        of the `filters` query parameter causes the URL to exceed the maximum
+        length of 8192 characters, resulting in a 413 Request Entity Too Large
+        response.
 
         The request `%s %s?filters={…}`, for example, is equivalent to  `%s %s`
-        with the body `{"filters": "{…}"}` in which any double quotes or
-        backslash characters inside `…` are escaped with another backslash. That
-        escaping is the requisite procedure for embedding one JSON structure
-        inside another.
+        with a `Content-Type` header of `application/json` and the body
+        `{"filters": "{…}"}` in which any double quotes or backslash characters
+        inside `…` are escaped with another backslash. That escaping is the
+        requisite procedure for embedding one JSON structure inside another.
     ''' % (method, endpoint, equivalent_method, endpoint))
 
 

lambdas/service/openapi.json

@@ -2497,7 +2497,7 @@
             "post": {
                 "summary": "\nSearch an index for entities of interest\n, with filters provided in the request body.\n",
                 "deprecated": true,
-                "description": "\nAny of the query parameters documented below can alternatively be passed\nas a property of a JSON object in the body of the request. This can be\nuseful in case the value of the `filters` query parameter causes the URL\nto exceed the maximum length of 8192 characters, resulting in a 413\nRequest Entity Too Large response.\n\nThe request `GET /index/files?filters={\u2026}`, for example, is equivalent to  `POST /index/files`\nwith the body `{\"filters\": \"{\u2026}\"}` in which any double quotes or\nbackslash characters inside `\u2026` are escaped with another backslash. That\nescaping is the requisite procedure for embedding one JSON structure\ninside another.\n\n\nNote that the Swagger UI can't currently be used to pass a body.\n\nPlease also note that this endpoint should be considered beta and\nmay change or disappear in the future. That is the reason for the\ndeprecation.\n",
+                "description": "\nAny of the query parameters documented below can alternatively be passed\nas a property of a JSON object in the body of the request. This is\nreferred to as *parameter hoisting* and can be useful in case the value\nof the `filters` query parameter causes the URL to exceed the maximum\nlength of 8192 characters, resulting in a 413 Request Entity Too Large\nresponse.\n\nThe request `GET /index/files?filters={\u2026}`, for example, is equivalent to  `POST /index/files`\nwith a `Content-Type` header of `application/json` and the body\n`{\"filters\": \"{\u2026}\"}` in which any double quotes or backslash characters\ninside `\u2026` are escaped with another backslash. That escaping is the\nrequisite procedure for embedding one JSON structure inside another.\n\n\nNote that the Swagger UI can't currently be used to pass a body.\n\nPlease also note that this endpoint should be considered beta and\nmay change or disappear in the future. That is the reason for the\ndeprecation.\n",
                 "tags": [
                     "Index"
                 ],
@@ -8533,7 +8533,7 @@
                     "Manifests"
                 ],
                 "summary": "Initiate the preparation of a manifest",
-                "description": "\nCreate a manifest preparation job, returning either\n\n- a 301 redirect to the URL of the status of that job or\n\n- a 302 redirect to the URL of an already prepared manifest.\n\nThis endpoint is not suitable for interactive use via the\nSwagger UI. Please use [PUT /fetch/manifest/files][1] instead.\n\n[1]: #operations-Manifests-put_fetch_manifest_files\n\nAny of the query parameters documented below can alternatively be passed\nas a property of a JSON object in the body of the request. This can be\nuseful in case the value of the `filters` query parameter causes the URL\nto exceed the maximum length of 8192 characters, resulting in a 413\nRequest Entity Too Large response.\n\nThe request `PUT /manifest/files?filters={\u2026}`, for example, is equivalent to  `PUT /manifest/files`\nwith the body `{\"filters\": \"{\u2026}\"}` in which any double quotes or\nbackslash characters inside `\u2026` are escaped with another backslash. That\nescaping is the requisite procedure for embedding one JSON structure\ninside another.\n",
+                "description": "\nCreate a manifest preparation job, returning either\n\n- a 301 redirect to the URL of the status of that job or\n\n- a 302 redirect to the URL of an already prepared manifest.\n\nThis endpoint is not suitable for interactive use via the\nSwagger UI. Please use [PUT /fetch/manifest/files][1] instead.\n\n[1]: #operations-Manifests-put_fetch_manifest_files\n\nAny of the query parameters documented below can alternatively be passed\nas a property of a JSON object in the body of the request. This is\nreferred to as *parameter hoisting* and can be useful in case the value\nof the `filters` query parameter causes the URL to exceed the maximum\nlength of 8192 characters, resulting in a 413 Request Entity Too Large\nresponse.\n\nThe request `PUT /manifest/files?filters={\u2026}`, for example, is equivalent to  `PUT /manifest/files`\nwith a `Content-Type` header of `application/json` and the body\n`{\"filters\": \"{\u2026}\"}` in which any double quotes or backslash characters\ninside `\u2026` are escaped with another backslash. That escaping is the\nrequisite procedure for embedding one JSON structure inside another.\n",
                 "parameters": [
                     {
                         "name": "catalog",
@@ -9995,7 +9995,7 @@
                     "Manifests"
                 ],
                 "summary": "Initiate the preparation of a manifest via XHR",
-                "description": "\nCreate a manifest preparation job, returning a 200 status\nresponse whose JSON body emulates the HTTP headers that would be\nfound in a response to an equivalent request to the [PUT\n/manifest/files][1] endpoint.\n\nWhenever client-side JavaScript code is used in a web\napplication to request the preparation of a manifest from Azul,\nthis endpoint should be used instead of [PUT\n/manifest/files][1]. This way, the client can use XHR to make\nthe request, retaining full control over the handling of\nredirects and enabling the client to bypass certain limitations\non the native handling of redirects in web browsers. For\nexample, most browsers ignore the `Retry-After` header in\nredirect responses, causing them to prematurely exhaust the\nupper limit on the number of consecutive redirects, before the\nmanifest generation job is done.\n\n[1]: #operations-Manifests-put_manifest_files\n\nAny of the query parameters documented below can alternatively be passed\nas a property of a JSON object in the body of the request. This can be\nuseful in case the value of the `filters` query parameter causes the URL\nto exceed the maximum length of 8192 characters, resulting in a 413\nRequest Entity Too Large response.\n\nThe request `PUT /fetch/manifest/files?filters={\u2026}`, for example, is equivalent to  `PUT /fetch/manifest/files`\nwith the body `{\"filters\": \"{\u2026}\"}` in which any double quotes or\nbackslash characters inside `\u2026` are escaped with another backslash. That\nescaping is the requisite procedure for embedding one JSON structure\ninside another.\n",
+                "description": "\nCreate a manifest preparation job, returning a 200 status\nresponse whose JSON body emulates the HTTP headers that would be\nfound in a response to an equivalent request to the [PUT\n/manifest/files][1] endpoint.\n\nWhenever client-side JavaScript code is used in a web\napplication to request the preparation of a manifest from Azul,\nthis endpoint should be used instead of [PUT\n/manifest/files][1]. This way, the client can use XHR to make\nthe request, retaining full control over the handling of\nredirects and enabling the client to bypass certain limitations\non the native handling of redirects in web browsers. For\nexample, most browsers ignore the `Retry-After` header in\nredirect responses, causing them to prematurely exhaust the\nupper limit on the number of consecutive redirects, before the\nmanifest generation job is done.\n\n[1]: #operations-Manifests-put_manifest_files\n\nAny of the query parameters documented below can alternatively be passed\nas a property of a JSON object in the body of the request. This is\nreferred to as *parameter hoisting* and can be useful in case the value\nof the `filters` query parameter causes the URL to exceed the maximum\nlength of 8192 characters, resulting in a 413 Request Entity Too Large\nresponse.\n\nThe request `PUT /fetch/manifest/files?filters={\u2026}`, for example, is equivalent to  `PUT /fetch/manifest/files`\nwith a `Content-Type` header of `application/json` and the body\n`{\"filters\": \"{\u2026}\"}` in which any double quotes or backslash characters\ninside `\u2026` are escaped with another backslash. That escaping is the\nrequisite procedure for embedding one JSON structure inside another.\n",
                 "parameters": [
                     {
                         "name": "catalog",