Merge 65612a0 into 373350e

projects/v1/wikipedia.wmf.yaml

@@ -90,6 +90,9 @@ paths:
       - path: v1/random.yaml
         options: '{{merge({"random_cache_control": "s-maxage=2, max-age=1"},
                       options.mobileapps)}}'
+      - path: v1/talk.yaml
+        options:
+          host: '{{options.mobileapps.host}}'
       - path: v1/pdf.js
         options: '{{options.pdf}}'
       - path: v1/common_schemas.yaml # Doesn't really matter where to mount it.

test/features/specification/monitoring.js

@@ -26,13 +26,22 @@ function constructTestCase(title, path, method, request, response) {
     };
 }
 
+function filterPath(paths, pathStr, method) {
+    const p = paths[pathStr][method];
+    if (p['x-amples'] && typeof p['x-monitor'] === 'undefined') {
+        throw new Error (`${'A Method that contains examples should declare x-monitor: true.'
+        + ' Path: '}${pathStr} Method: ${method}`)
+    }
+    return p['x-monitor'];
+}
+
 function constructTests(spec, options, server) {
     const paths = spec.paths;
     const ret = [];
     Object.keys(paths).forEach((pathStr) => {
         if (!pathStr) { return; }
         Object.keys(paths[pathStr]).filter((method) => {
-            return paths[pathStr][method]['x-monitor'];
+            return filterPath(paths, pathStr, method);
         })
         .forEach((method) => {
             const p = paths[pathStr][method];

v1/talk.yaml

@@ -0,0 +1,142 @@
+openapi: 3.0.1
+info:
+  version: 0.1.0
+  title: MediaWiki Structured Talk page API
+  description: API for retrieving structured representation of the talk page
+  termsOfService: https://www.mediawiki.org/wiki/REST_API#Terms_and_conditions
+  contact:
+    name: Reading Infrastructure
+    url: https://www.mediawiki.org/wiki/Wikimedia_Reading_Infrastructure_team
+  license:
+    name: Apache licence, v2
+    url: https://www.apache.org/licenses/LICENSE-2.0
+paths:
+  /talk/{title}:
+    x-route-filters: &talk_title_revision_filter
+      - path: ./lib/access_check_filter.js
+        options:
+          redirect_cache_control: '{{options.response_cache_control}}'
+      - path: lib/security_response_header_filter.js
+    get: &talk_title_revision_get_spec
+      tags:
+        - Talk pages
+      summary: Get structured talk page contents
+      description: Gets structured talk page contents for the provided title.
+      parameters:
+        - name: title
+          in: path
+          description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.'
+          required: true
+          schema:
+            type: string
+        - name: redirect
+          in: query
+          description: |
+            Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body.
+            To get a 200 response instead, supply `false` to the `redirect` parameter.
+          schema:
+            type: boolean
+      responses:
+        200:
+          description: structured talk page JSON.
+          headers:
+            ETag:
+              description: |
+                Syntax: "{revision}/{tid}". Example: "701384379/154d7bca-c264-11e5-8c2f-1b51b33b59fc"
+              schema:
+                type: string
+          content:
+            application/json; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/Talk/0.1.0":
+              schema:
+                type: string
+        301:
+          description: |
+            A permanent redirect is returned if the supplied article title was not in the normalized form.
+            To avoid this kind of redirect, you can use the [mediawiki-title](https://github.com/wikimedia/mediawiki-title) library to perform
+            title normalization client-side.
+
+            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
+            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
+        302:
+          description: |
+            The page is a [redirect page](https://www.mediawiki.org/wiki/Help:Redirects).
+            The `location` header points to the redirect target.
+            If you would like to avoid automatically following redirect pages, set the `redirect=false` query parameter.
+
+            Beware that redirected pre-flighted cross-origin requests (such as those sending custom request headers like `Api-User-Agent`)
+            will fail in most current browsers [due to a spec bug](https://github.com/whatwg/fetch/issues/204).
+        404:
+          description: Unknown page title
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/problem'
+        default:
+          description: Error
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/problem'
+      x-request-handler:
+        - get_from_pcs:
+            request:
+              method: get
+              headers:
+                accept-language: '{{accept-language}}'
+              uri: '{{options.host}}/{domain}/v1/page/talk/{title}{/revision}'
+            return:
+              status: 200
+              headers: '{{ get_from_pcs.headers }}'
+              body: '{{get_from_pcs.body}}'
+      x-monitor: true
+      x-amples:
+        - title: Get structured talk page for enwiki Salt article
+          request:
+            params:
+              domain: en.wikipedia.org
+              title: Salt
+          response:
+            status: 200
+            headers:
+              content-type: /application\/json; charset=utf-8; profile=".+Talk.+"/
+              etag: /^"[^/"]+/[^/"]+"$/
+            body:
+              topics:
+                - id: /.+/
+                  replies:
+                    - sha: /.+/
+                      depth: /.+/
+                      html: /.*/
+                  depth: /.+/
+                  html: /.*/
+                  shas:
+                    html: /.+/
+                    indicator: /.+/
+
+  /talk/{title}/{revision}:
+    x-route-filters:
+      <<: *talk_title_revision_filter
+    get:
+      <<: *talk_title_revision_get_spec
+      parameters:
+        - name: title
+          in: path
+          description: 'Page title. Use underscores instead of spaces. Example: `Main_Page`.'
+          required: true
+          schema:
+            type: string
+        - name: revision
+          in: path
+          description: |
+            Optional page revision. Note that older revisions are not stored, so request latency with the revision would be higher.
+          required: true
+          schema:
+            type: integer
+        - name: redirect
+          in: query
+          description: |
+            Requests for [redirect pages](https://www.mediawiki.org/wiki/Help:Redirects) return HTTP 302 with a redirect target in `Location` header and content in the body.
+            To get a 200 response instead, supply `false` to the `redirect` parameter.
+          schema:
+            type: boolean
+      x-monitor: false