From aefefbcd88d583d79a9a558fcf5e5cab8c24275b Mon Sep 17 00:00:00 2001
From: Matt Marshall <matt@mrshll.uk>
Date: Thu, 12 Sep 2024 08:48:41 +0100
Subject: [PATCH] schema/openapi: POST method on several endpoints

Added POST method on the following endpoints:

* /services
* /taxonomies
* /taxonomy_terms
* /organizations
* /service_at_locations

As per proposal:

* https://docs.google.com/document/d/1UEek9HmDNxJmJUqqB1N8JM7g-KFyEE8g-W9qR1f_Y_0/view
---
 schema/openapi.json | 285 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 285 insertions(+)

diff --git a/schema/openapi.json b/schema/openapi.json
index f66ad1e..c83d657 100644
--- a/schema/openapi.json
+++ b/schema/openapi.json
@@ -145,6 +145,69 @@
             }
           }
         }
+      },
+      "post": {
+        "description": "Retrieve fully nested service with all related data with id.",
+        "summary": "Retrieves paginated listings of services that only have one-to-one fields in them.",
+        "operationId": "getPaginatedListOfServices",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/search"
+          },
+          {
+            "$ref": "#/components/parameters/page"
+          },
+          {
+            "$ref": "#/components/parameters/per_page"
+          },
+          {
+            "$ref": "#/components/parameters/format"
+          },
+          {
+            "$ref": "#/components/parameters/taxonomy_term_id"
+          },
+          {
+            "$ref": "#/components/parameters/taxonomy_id"
+          },
+          {
+            "$ref": "#/components/parameters/organization_id"
+          },
+          {
+            "$ref": "#/components/parameters/modified_after"
+          },
+          {
+            "description": "Return array of just services with just 'id' and 'modified_date'.  When using this parameter aim to return all services within one page.",
+            "$ref": "#/components/parameters/minimal"
+          },
+          {
+            "description": "true, false return fully nested service.",
+            "$ref": "#/components/parameters/full"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A paginated list of services that only have one-to-one fields in them.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "contents": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "https://raw.githubusercontent.com/openreferral/specification/3.0/schema/compiled/service_list.json"
+                      }
+                    }
+                  },
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/Page"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
       }
     },
     "/taxonomies/{id}": {
@@ -220,6 +283,49 @@
             }
           }
         }
+      },
+      "post": {
+        "description": "Paginated listing of taxonomies.",
+        "summary": "Paginated listing of taxonomies.",
+        "operationId": "getPaginatedListOfTaxonomies",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/search"
+          },
+          {
+            "$ref": "#/components/parameters/page"
+          },
+          {
+            "$ref": "#/components/parameters/per_page"
+          },
+          {
+            "$ref": "#/components/parameters/format"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Paginated listing of taxonomies.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "contents": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "https://raw.githubusercontent.com/openreferral/specification/3.0/schema/taxonomy.json"
+                      }
+                    }
+                  },
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/Page"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
       }
     },
     "/taxonomy_terms/{id}": {
@@ -316,6 +422,70 @@
             }
           }
         }
+      },
+      "post": {
+        "description": "Full information on a taxonomy term",
+        "summary": "Paginated listing of taxonomy terms",
+        "operationId": "getTaxonomyTermById",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/search"
+          },
+          {
+            "$ref": "#/components/parameters/page"
+          },
+          {
+            "$ref": "#/components/parameters/per_page"
+          },
+          {
+            "$ref": "#/components/parameters/format"
+          },
+          {
+            "$ref": "#/components/parameters/taxonomy_id"
+          },
+          {
+            "name": "top_only",
+            "in": "query",
+            "required": false,
+            "description": "Only retrieve taxonomy terms that have not child terms.",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "parent_id",
+            "in": "query",
+            "required": false,
+            "description": "Recieve taxonomy terms that have a parent with this id.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Paginated listing of taxonomy terms",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "contents": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "https://raw.githubusercontent.com/openreferral/specification/3.0/schema/taxonomy_term.json"
+                      }
+                    }
+                  },
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/Page"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
       }
     },
     "/organizations/{id}": {
@@ -403,6 +573,56 @@
             }
           }
         }
+      },
+      "post": {
+        "description": "Paginated list of basic Organization information.",
+        "summary": "Paginated list of basic Organization information",
+        "operationId": "getPaginatedListOfOrganizations",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/search"
+          },
+          {
+            "$ref": "#/components/parameters/full_service"
+          },
+          {
+            "description": "Contains full nested organization information",
+            "$ref": "#/components/parameters/full"
+          },
+          {
+            "$ref": "#/components/parameters/page"
+          },
+          {
+            "$ref": "#/components/parameters/per_page"
+          },
+          {
+            "$ref": "#/components/parameters/format"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Paginated list of basic Organization information.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "contents": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "https://raw.githubusercontent.com/openreferral/specification/3.0/schema/compiled/organization_list.json"
+                      }
+                    }
+                  },
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/Page"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
       }
     },
     "/service_at_locations/{id}": {
@@ -500,6 +720,71 @@
             }
           }
         }
+      },
+      "post": {
+        "description": "Retrieve paginated listings of service_at_location that only have one-to-one fields in them.",
+        "summary": "Retrieve paginated listings of service_at_location that only have one-to-one fields in them.",
+        "operationId": "getPaginatedListOfServiceAtLocation",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/search"
+          },
+          {
+            "$ref": "#/components/parameters/taxonomy_term_id"
+          },
+          {
+            "$ref": "#/components/parameters/taxonomy_id"
+          },
+          {
+            "$ref": "#/components/parameters/organization_id"
+          },
+          {
+            "$ref": "#/components/parameters/modified_after"
+          },
+          {
+            "description": "true, false return fully nested service_at_location.",
+            "$ref": "#/components/parameters/full"
+          },
+          {
+            "$ref": "#/components/parameters/page"
+          },
+          {
+            "$ref": "#/components/parameters/per_page"
+          },
+          {
+            "$ref": "#/components/parameters/format"
+          },
+          {
+            "$ref": "#/components/parameters/postcode"
+          },
+          {
+            "$ref": "#/components/parameters/proximity"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Retrieve paginated listings of service_at_location that only have one-to-one fields in them.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "contents": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "https://raw.githubusercontent.com/openreferral/specification/3.0/schema/compiled/service_at_location_list.json"
+                      }
+                    }
+                  },
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/Page"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
       }
     }
   },