[FCL-351] Document atom feed

doc/openapi/public_api.yml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: "National Archives Find Case Law: Public API"
-  version: 0.1.3
+  version: 0.2.0
   description: |-
     Our API provides access to judgments and decisions held by Find Case Law that have been converted from Microsoft Word documents into XML. These have been automatically marked up according to the [international data standard, LegalDocML](https://groups.oasis-open.org/communities/tc-community-home2?CommunityKey=3425f20f-b704-4076-9fab-018dc7d3efbe), and validated by our legal editorial team. This data includes:
 
@@ -37,8 +37,8 @@ info:
     url: "https://caselaw.nationalarchives.gov.uk/open-justice-licence"
   summary: "The Find Case Law API allows you to access court judgments and tribunal decisions held in the [Find Case Law service](https://caselaw.nationalarchives.gov.uk/), operated by the National Archives."
 servers:
-  - url: "https://caselaw.nationalarchives.gov.uk"
-    description: ""
+  - url: "https://caselaw.nationalarchives.gov.uk/"
+    description: "Find Case Law"
 components:
   parameters:
     documentUri:
@@ -50,23 +50,128 @@ components:
       example: ewhc/tcc/2022/42
       description: The unique identifier for this document within Find Case Law.
   responses:
-    judgmentFeed:
-      description: An Atom feed of recently published judgments
+    documentFeed:
+      description: |
+        An Atom feed of documents, sorted by one of the dates within those documents.
       content:
         application/atom+xml:
           schema:
             description: List in Atom
-    judgment:
+    document:
       description: "The contents of a single document, as [Akoma Ntoso XML](https://www.oasis-open.org/standard/akn-v1-0/)."
       content:
         application/akn+xml:
           schema:
             description: Akoma Ntoso
 paths:
+  "/atom.xml":
+    get:
+      summary: Get a Atom feed of documents
+      description: |
+        Without any parameters, this will give the most recently handed down judgments and decisions. The parameters used are identical to
+        those used for the advanced search at https://caselaw.nationalarchives.gov.uk/judgments/search: a link to the feed mirroring those
+        search results is available on each search result.
+
+        Each differently named parameter filters out documents that do not match it.
+
+        The feed has multiple pages (see the `link` tag with a `rel` attribute of `next` for the next page).
+
+        Each `entry` tag contains a different document's metadata. Notable tags include:
+        * `<tna:contenthash>`: A hash of the text in the judgment, with whitespace removed. Can be used to determine if the underlying judgment text has changed.
+        *  `<tna:xml>`: The location at which the XML of the document can be found
+        *  `<tna:uri>`: The identifier for the document
+        *  `<tna:pdf>`: The location of a PDF version of the judgment: this is not guaranteed to exist.
+
+      operationId: atomFeed
+      parameters:
+        - name: query
+          required: false
+          in: query
+          schema:
+            type: string
+          description: |
+            Full text search of a judgment. `"financial records"` will only find judgments with those two words in that order. Multiple
+            space-separated words will only find judgments that have all those words.
+        # todo: from_ and to_date_0, _1, _2, 2 is year
+        - name: court
+          required: false
+          # can be multiple
+          in: query
+          schema:
+            type: string
+          description: |
+            A court code. Currently there are two forms of court code, one used in the URL structure (`ewhc/fam`) and one used in the XML
+            court tag `EWHC-Family`. Either can be searched for. If multiple courts or tribunals are given, results from all those courts
+            may be returned.
+        - name: tribunal
+          required: false
+          # can be multiple
+          in: query
+          schema:
+            type: string
+          description: |
+            A tribunal. Identical to the court codes above.
+        - name: party
+          required: false
+          in: query
+          schema:
+            type: string
+          description: |
+            A full-match for a word in the name of a party to the judgment.
+        - name: judge
+          required: false
+          in: query
+          schema:
+            type: string
+          description: |
+            A full-match for a word in the name of a judge or similar involved in the judgment
+        - name: order
+          required: false
+          in: query
+          schema:
+            type: string
+            enum:
+              - date
+              - "-date"
+              - updated
+              - "-updated"
+              - transformation
+              - "-transformation"
+            default: "-date"
+          description: |
+            Which of the dates within the document to use for ordering. Prepend a `-` to sort by newest first.
+
+            - `date`: The date the document was first published by the court
+            - `updated`: The last date the document was updated in the Find Case Law system, including changes to its metadata
+            - `transformation`: The date the body of the document was last modified, including changes to either the body text, XML markup, or both
+        - name: page
+          required: false
+          in: query
+          schema:
+            type: integer
+            default: 1
+            minimum: 1
+          description: "Where results are across multiple pages, the page of results to return."
+        - name: per_page
+          required: false
+          in: query
+          schema:
+            type: integer
+            default: 50
+          description: |
+            How many results to list per page.
+      responses:
+        "200":
+          $ref: "#/components/responses/documentFeed"
+      tags:
+        - Reading documents
+
   "/{court}/{subdivision}/{year}/atom.xml":
     get:
       summary: Get a list of recently published or updated documents
       description: |
+        Deprecated -- will now redirect to /atom.xml with relevant parameters
+
         Less specific feeds can be gained by omitting the components e.g. `/`, `/2022/`, `/ewhc/` and `/ewhc/ch/` are all valid prefixes to `atom.xml`.
 
         Note that a `{court}` is required if there is a `{subdivision}`.
@@ -100,10 +205,16 @@ paths:
             minimum: 1
           description: "Where results are across multiple pages, the page of results to return."
       responses:
-        "200":
-          $ref: "#/components/responses/judgmentFeed"
+        "301":
+          description: Moved Permanently
+          headers:
+            location:
+              schema:
+                type: string
+              description: "https://caselaw.nationalarchives.gov.uk/atom.xml?court={court}/{subdivision}&year={year}&order=-date&page=1"
       tags:
         - Reading documents
+      deprecated: true
     parameters:
       - name: court
         required: true
@@ -132,7 +243,7 @@ paths:
       operationId: getDocumentByUri
       responses:
         "200":
-          $ref: "#/components/responses/judgment"
+          $ref: "#/components/responses/document"
       tags:
         - Reading documents
       description: Retrieve the XML of a single document based on its identifier.