test: add service error 500 case, strengthen order assertion, drop batch_eligible from catalog

Author: Kinnouts

apps/api/services/text/spellcheck/transport_http_test.go

@@ -126,11 +126,12 @@ func TestSpellcheckBatch_MixedTexts(t *testing.T) {
 
 func TestSpellcheckBatch_OrderPreserved(t *testing.T) {
 	t.Parallel()
+	// No matches returned — so Corrected equals the original text for every
+	// item, letting us assert that each result maps to the right input position.
 	lt := newMockLT(t, []ltMatch{})
 	defer lt.Close()
 	r := setupRouter(lt.URL)
 
-	// RFC requires results to stay in the same order as the input array.
 	body := `{"texts":["Hello world","Clean text","More clean text"]}`
 	req := httptest.NewRequest(http.MethodPost, "/spellcheck/batch", strings.NewReader(body))
 	req.Header.Set("Content-Type", "application/json")
@@ -142,6 +143,9 @@ func TestSpellcheckBatch_OrderPreserved(t *testing.T) {
 	var resp httpx.Response[BatchCheckResponse]
 	require.NoError(t, json.NewDecoder(w.Body).Decode(&resp))
 	require.Len(t, resp.Data.Results, 3)
+	assert.Equal(t, "Hello world", resp.Data.Results[0].Corrected)
+	assert.Equal(t, "Clean text", resp.Data.Results[1].Corrected)
+	assert.Equal(t, "More clean text", resp.Data.Results[2].Corrected)
 }
 
 func TestSpellcheckBatch_UsageCountHeader(t *testing.T) {
@@ -222,3 +226,18 @@ func TestSpellcheckBatch_MissingBody(t *testing.T) {
 
 	assert.Equal(t, http.StatusBadRequest, w.Code)
 }
+
+func TestSpellcheckBatch_ServiceError(t *testing.T) {
+	t.Parallel()
+	// Point the service at a port where nothing is listening so every
+	// LanguageTool call fails, simulating an unreachable backend.
+	r := setupRouter("http://localhost:19999")
+
+	body := `{"texts":["Hello world","Clean text"]}`
+	req := httptest.NewRequest(http.MethodPost, "/spellcheck/batch", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusInternalServerError, w.Code)
+}

apps/dashboard/config/api_catalog.yml

@@ -429,7 +429,6 @@ apis:
       - text
     description: Check spelling and get correction suggestions for misspelled words
     endpoints_count: 2
-    batch_eligible: true
     status: live
     popular: true
     documentation_url: /apis/spell-check

apps/dashboard/config/api_docs/spell-check.yml

@@ -11,11 +11,11 @@ overview:
     - Form validation and input sanitisation
     - Educational platforms and grammar tools
   features:
-    - Detects misspelled words using an English dictionary
-    - Provides the best correction suggestion per misspelled word
+    - Detects misspelled words and grammar issues using LanguageTool
+    - Returns the best correction and up to 3 ranked alternative suggestions per misspelled word
     - Returns character positions for each correction
-    - Preserves original capitalisation in suggestions
-    - Only ASCII letter sequences are spell-checked; non-ASCII characters are passed through unchanged
+    - Supports full Unicode input including accented and non-Latin characters
+    - Batch endpoint processes up to 50 texts in a single request
 endpoints:
   - name: Check Spelling
     method: POST
@@ -37,9 +37,24 @@ endpoints:
         "data": {
           "corrected": "This is a simple test",
           "corrections": [
-            {"original": "Ths", "suggested": "This", "position": 0},
-            {"original": "smiple", "suggested": "simple", "position": 9},
-            {"original": "tset", "suggested": "test", "position": 16}
+            {
+              "original": "Ths",
+              "suggested": "This",
+              "suggestions": ["Th's", "Th", "This"],
+              "position": 0
+            },
+            {
+              "original": "smiple",
+              "suggested": "simple",
+              "suggestions": ["simple", "smile", "Siple"],
+              "position": 9
+            },
+            {
+              "original": "tset",
+              "suggested": "test",
+              "suggestions": ["set", "test", "stet"],
+              "position": 16
+            }
           ]
         },
         "metadata": {
@@ -49,12 +64,13 @@ endpoints:
     response_fields:
       - name: corrected
         type: string
-        description: The full input text with all misspelled words replaced by their suggested corrections
+        description: The full input text with all misspelled words replaced by the top-ranked suggestion
       - name: corrections
         type: array of objects
         description: >-
           List of individual corrections. Each item contains: original (the misspelled word), suggested (the
-          correction), and position (0-based character offset in the original text)
+          top-ranked replacement applied to corrected), suggestions (up to 3 ranked alternatives returned by
+          LanguageTool, from most to least likely), and position (0-based Unicode character offset in the original text)
     errors:
       - code: validation_failed
         status: 422
@@ -135,14 +151,29 @@ endpoints:
             {
               "corrected": "This is a test",
               "corrections": [
-                {"original": "Ths", "suggested": "This", "position": 0},
-                {"original": "tset", "suggested": "test", "position": 9}
+                {
+                  "original": "Ths",
+                  "suggested": "This",
+                  "suggestions": ["Th's", "Th", "This"],
+                  "position": 0
+                },
+                {
+                  "original": "tset",
+                  "suggested": "test",
+                  "suggestions": ["set", "test", "stet"],
+                  "position": 9
+                }
               ]
             },
             {
               "corrected": "Simple example",
               "corrections": [
-                {"original": "Smiple", "suggested": "Simple", "position": 0}
+                {
+                  "original": "Smiple",
+                  "suggested": "Simple",
+                  "suggestions": ["Simple", "Smile", "Siple"],
+                  "position": 0
+                }
               ]
             }
           ],
@@ -155,7 +186,9 @@ endpoints:
     response_fields:
       - name: results
         type: array of objects
-        description: One entry per input text, in the same order as the input array. Each item contains corrected (the fixed text) and corrections (list of individual corrections with original, suggested, and position).
+        description: >-
+          One entry per input text, in the same order as the input array. Each item contains corrected (the fixed
+          text) and corrections (list of individual corrections with original, suggested, suggestions, and position).
       - name: total
         type: integer
         description: Number of texts processed. Equals the length of the input array.
@@ -219,17 +252,20 @@ endpoints:
         data['data']['results'].each { |item| puts item['corrected'] }
 faq:
   - question: What language does spell check support?
-    answer: The spell checker currently supports English only.
+    answer: The spell checker currently processes text as English (en-US). Multi-language support is planned for a future release.
   - question: Are positions zero-indexed?
     answer: >-
       Yes. The position field is a 0-based Unicode character (rune) offset in the original input string. This matches
       how Python, JavaScript, and Ruby index strings.
   - question: What happens if the text has no spelling mistakes?
     answer: "The corrected field will equal the input text and corrections will be an empty array: []."
-  - question: Does capitalisation affect the correction?
+  - question: What is the difference between suggested and suggestions?
     answer: >-
-      No. Spell checking is case-insensitive. The suggested correction mirrors the capitalisation of the original word:
-      a capitalised misspelling produces a capitalised suggestion.
+      suggested is the single best replacement, already applied to the corrected text. suggestions is an ordered list
+      of up to 3 alternatives returned by LanguageTool (from most to least likely), which you can use to present a
+      correction picker to your users instead of applying the first option automatically.
+  - question: How many items can I send in a batch request?
+    answer: Between 1 and 50 texts per request. Requests with an empty array or more than 50 items return 422.
 performance:
   p50_ms: 807
   p95_ms: 1147