Add API endpoints for documents (#1398)

DistributedProofreaders · Dec 22, 2024 · 4ed1635 · 4ed1635
1 parent d006260
commit 4ed1635
Show file tree

Hide file tree

Showing 6 changed files with 140 additions and 4 deletions.
diff --git a/SETUP/tests/unittests/ApiTest.php b/SETUP/tests/unittests/ApiTest.php
@@ -772,7 +772,7 @@ public function test_wordcheck_report(): void
         $this->assertEquals($accepted_words, $result[4]);
     }
 
-    public function test_pickersets()
+    public function test_pickersets(): void
     {
         $project = $this->_create_project();
         $path = "v1/projects/$project->projectid/pickersets";
@@ -786,6 +786,43 @@ public function test_pickersets()
         $this->assertEquals(["!", "EXCLAMATION MARK"], $pickerset["subsets"][3]["rows"][0][0]);
         $this->assertEquals(["¿", "INVERTED QUESTION MARK"], $pickerset["subsets"][3]["rows"][1][1]);
     }
+
+    public function test_available_italian_documents(): void
+    {
+        $path = "v1/documents";
+        $router = ApiRouter::get_router();
+        $_SERVER["REQUEST_METHOD"] = "GET";
+        $response = $router->route($path, ['language_code' => 'it']);
+        $this->assertEquals(["proofreading_guidelines.php", "formatting_guidelines.php"], $response);
+    }
+
+    public function test_available_document(): void
+    {
+        $path = "v1/documents/cp.php";
+        $router = ApiRouter::get_router();
+        $_SERVER["REQUEST_METHOD"] = "GET";
+        $response = $router->route($path, ['language_code' => 'fr']);
+        $this->assertEquals("https://www.pgdp.net/wiki/DP_Official_Documentation:CP_and_PM/French/FAQ_fourniture_de_contenu", $response);
+    }
+
+    public function test_default_document(): void
+    {
+        $path = "v1/documents/cp.php";
+        $router = ApiRouter::get_router();
+        $_SERVER["REQUEST_METHOD"] = "GET";
+        $response = $router->route($path, []);
+        $this->assertEquals("https://www.pgdp.net/wiki/DP_Official_Documentation:CP_and_PM/Content_Providing_FAQ", $response);
+    }
+
+    public function test_unavailable_document(): void
+    {
+        $this->expectExceptionMessage("cp.php is not available in language code 'de'");
+
+        $path = "v1/documents/cp.php";
+        $router = ApiRouter::get_router();
+        $_SERVER["REQUEST_METHOD"] = "GET";
+        $router->route($path, ['language_code' => 'de']);
+    }
 }
 
 // this mocks the function in index.php

diff --git a/api/dp-openapi.yaml b/api/dp-openapi.yaml
@@ -1290,6 +1290,54 @@ paths:
               schema:
                 $ref: '#/components/schemas/round_stats'
 
+  /documents:
+    get:
+      tags:
+      - documents
+      description: Gets an array of available documents. If language_code is given, only documents available in that language are returned.
+      parameters:
+      - name: language_code
+        in: query
+        description: Two-letter (ISO 639-1) language code.
+        schema:
+          type: string
+      responses:
+        200:
+          description: Array of document filenames
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+
+  /documents/{document}:
+    get:
+      tags:
+      - documents
+      description: Gets a URL for the given document in language_code (if specified and available) or English.
+      parameters:
+      - name: document
+        in: path
+        description: filename of the document
+        required: true
+        schema:
+          type: string
+      - name: language_code
+        in: query
+        description: Two-letter (ISO 639-1) language code.
+        schema:
+          type: string
+      responses:
+        200:
+          description: URL for the document
+          content:
+            application/json:
+              schema:
+                type: string
+        404:
+          $ref: '#/components/responses/NotFound'
+
 components:
   securitySchemes:
     ApiKeyAuth:

diff --git a/api/v1.inc b/api/v1.inc
@@ -6,6 +6,7 @@ include_once("v1_validators.inc");
 include_once("v1_projects.inc");
 include_once("v1_queues.inc");
 include_once("v1_stats.inc");
+include_once("v1_docs.inc");
 
 $router = ApiRouter::get_router();
 
@@ -16,8 +17,12 @@ $router->add_validator(":roundid", "validate_round");
 $router->add_validator(":pagename", "validate_page_name");
 $router->add_validator(":pageroundid", "validate_page_round");
 $router->add_validator(":queueid", "validate_release_queue");
+$router->add_validator(":document", "validate_document");
 
 // Add routes
+$router->add_route("GET", "v1/documents", "api_v1_documents");
+$router->add_route("GET", "v1/documents/:document", "api_v1_document");
+
 $router->add_route("GET", "v1/projects", "api_v1_projects");
 $router->add_route("POST", "v1/projects", "api_v1_project");
 $router->add_route("GET", "v1/projects/difficulties", "api_v1_projects_difficulties");

diff --git a/api/v1_docs.inc b/api/v1_docs.inc
@@ -0,0 +1,31 @@
+<?php
+include_once($relPath.'faq.inc');
+
+function api_v1_documents(string $method, array $data, array $query_params): array
+{
+    global $external_faq_overrides;
+
+    $lang_code = $query_params["language_code"] ?? null;
+    if ($lang_code) {
+        $docs_with_lang = [];
+        foreach ($external_faq_overrides as $doc => $doc_array) {
+            if (isset($doc_array[$lang_code])) {
+                $docs_with_lang[] = $doc;
+            }
+        }
+        return $docs_with_lang;
+    } else {
+        return array_keys($external_faq_overrides);
+    }
+}
+
+function api_v1_document(string $method, array $data, array $query_params): string
+{
+    $lang_code = $query_params["language_code"] ?? "en";
+    $document = $data[":document"];
+    $faq_url = get_faq_url($document, $lang_code, false);
+    if ("" === $faq_url) {
+        throw new NotFoundError("$document is not available in language code '$lang_code'");
+    }
+    return $faq_url;
+}
diff --git a/api/v1_validators.inc b/api/v1_validators.inc
@@ -67,3 +67,13 @@ function validate_release_queue($queueid, $data)
     }
     return $queue_data;
 }
+
+function validate_document(string $document): string
+{
+    global $external_faq_overrides;
+
+    if (!array_key_exists($document, $external_faq_overrides)) {
+        throw new NotFoundError("document $document not found");
+    }
+    return $document;
+}
diff --git a/pinc/faq.inc b/pinc/faq.inc
@@ -63,7 +63,7 @@ $external_faq_overrides = [
 ];
 
 
-function get_faq_url(string $faq, ?string $langcode = null): string
+function get_faq_url(string $faq, ?string $langcode = null, bool $english_fallback = true): string
 {
     global $code_dir, $code_url;
 
@@ -72,8 +72,13 @@ function get_faq_url(string $faq, ?string $langcode = null): string
         $langcode = substr(get_desired_language(), 0, 2);
     }
 
+    $check_lang_codes = [$langcode];
+    if ($english_fallback) {
+        array_push($check_lang_codes, "en");
+    }
+
     // first try $langcode, then English
-    foreach ([$langcode, "en"] as $langcode) {
+    foreach ($check_lang_codes as $langcode) {
         // Any overrides?
         $external_faq = get_external_faq($faq, $langcode);
         if ($external_faq) {
@@ -87,7 +92,7 @@ function get_faq_url(string $faq, ?string $langcode = null): string
     }
 
     // fall back to the English version in the code if it exists
-    if (is_file("$code_dir/faq/$faq")) {
+    if ($english_fallback && is_file("$code_dir/faq/$faq")) {
         return "$code_url/faq/$faq";
     }