From 537714cb6cdc4a3ad0ee460c07f7f271c755d263 Mon Sep 17 00:00:00 2001
From: Daniel Lockyer <hi@daniellockyer.com>
Date: Thu, 11 Aug 2022 17:29:08 +0200
Subject: [PATCH] Moved API documentation to api-framework README

- it's better suited here given this package is now the API framework
---
 ghost/api-framework/README.md        | 131 ++++++++++++++++++++++++++-
 ghost/core/core/server/api/README.md | 130 --------------------------
 2 files changed, 129 insertions(+), 132 deletions(-)
 delete mode 100644 ghost/core/core/server/api/README.md

diff --git a/ghost/api-framework/README.md b/ghost/api-framework/README.md
index 64191b307a..9d31c3939c 100644
--- a/ghost/api-framework/README.md
+++ b/ghost/api-framework/README.md
@@ -1,10 +1,137 @@
-# Api Framework
+# API Framework
 
 API framework used by Ghost
 
-
 ## Usage
 
+### Stages
+
+Each request goes through the following stages:
+
+- input validation
+- input serialisation
+- permissions
+- query
+- output serialisation
+
+The framework we are building pipes a request through these stages in respect of the API controller configuration.
+
+
+### Frame
+
+Is a class, which holds all the information for request processing. We pass this instance by reference.
+Each function can modify the original instance. No need to return the class instance.
+
+#### Structure
+
+```
+{
+  original: Object,
+  options: Object,
+  data: Object,
+  user: Object,
+  file: Object,
+  files: Array
+}
+```
+
+#### Example
+
+```
+{
+  original: {
+    include: 'tags'
+  },
+  options: {
+    withRelated: ['tags']
+  },
+  data: {
+    posts: []
+  }
+}
+```
+
+### API Controller
+
+A controller is no longer just a function, it's a set of configurations.
+
+#### Structure
+
+```
+edit: function || object
+```
+
+```
+edit: {
+  headers: object,
+  options: Array,
+  data: Array,
+  validation: object | function,
+  permissions: boolean | object | function,
+  query: function
+}
+```
+
+#### Examples
+
+
+```
+edit: {
+  headers: {
+    cacheInvalidate: true
+  },
+  // Allowed url/query params
+  options: ['include']
+  // Url/query param validation configuration
+  validation: {
+    options: {
+      include: {
+        required: true,
+        values: ['tags']
+      }
+    }
+  },
+  permissions: true,
+  // Returns a model response!
+  query(frame) {
+    return models.Post.edit(frame.data, frame.options);
+  }
+}
+```
+
+```
+read: {
+  // Allowed url/query params, which will be remembered inside `frame.data`
+  // This is helpful for READ requests e.g. `model.findOne(frame.data, frame.options)`.
+  // Our model layer requires sending the where clauses as first parameter.
+  data: ['slug']
+  validation: {
+    data: {
+      slug: {
+        values: ['eins']
+      }
+    }
+  },
+  permissions: true,
+  query(frame) {
+    return models.Post.findOne(frame.data, frame.options);
+  }
+}
+```
+
+```
+edit: {
+  validation() {
+    // custom validation, skip framework
+  },
+  permissions: {
+    unsafeAttrs: ['author']
+  },
+  query(frame) {
+    return models.Post.edit(frame.data, frame.options);
+  }
+}
+```
 
 ## Develop
 
diff --git a/ghost/core/core/server/api/README.md b/ghost/core/core/server/api/README.md
deleted file mode 100644
index fc9dfe7400..0000000000
--- a/ghost/core/core/server/api/README.md
+++ /dev/null
@@ -1,130 +0,0 @@
-# API
-
-## Stages
-
-Each request goes through the following stages:
-
-- input validation
-- input serialisation
-- permissions
-- query
-- output serialisation
-
-The framework we are building pipes a request through these stages in respect of the API controller configuration.
-
-
-## Frame
-
-Is a class, which holds all the information for request processing. We pass this instance by reference.
-Each function can modify the original instance. No need to return the class instance.
-
-### Structure
-
-```
-{
-  original: Object,
-  options: Object,
-  data: Object,
-  user: Object,
-  file: Object,
-  files: Array
-}
-```
-
-### Example
-
-```
-{
-  original: {
-    include: 'tags'
-  },
-  options: {
-    withRelated: ['tags']
-  },
-  data: {
-    posts: []
-  }
-}
-```
-
-## API Controller
-
-A controller is no longer just a function, it's a set of configurations.
-
-### Structure
-
-```
-edit: function || object
-```
-
-```
-edit: {
-  headers: object,
-  options: Array,
-  data: Array,
-  validation: object | function,
-  permissions: boolean | object | function,
-  query: function
-}
-```
-
-### Examples
-
-
-```
-edit: {
-  headers: {
-    cacheInvalidate: true
-  },
-  // Allowed url/query params
-  options: ['include']
-  // Url/query param validation configuration
-  validation: {
-    options: {
-      include: {
-        required: true,
-        values: ['tags']
-      }
-    }
-  },
-  permissions: true,
-  // Returns a model response!
-  query(frame) {
-    return models.Post.edit(frame.data, frame.options);
-  }
-}
-```
-
-```
-read: {
-  // Allowed url/query params, which will be remembered inside `frame.data`
-  // This is helpful for READ requests e.g. `model.findOne(frame.data, frame.options)`.
-  // Our model layer requires sending the where clauses as first parameter.
-  data: ['slug']
-  validation: {
-    data: {
-      slug: {
-        values: ['eins']
-      }
-    }
-  },
-  permissions: true,
-  query(frame) {
-    return models.Post.findOne(frame.data, frame.options);
-  }
-}
-```
-
-```
-edit: {
-  validation() {
-    // custom validation, skip framework
-  },
-  permissions: {
-    unsafeAttrs: ['author']
-  },
-  query(frame) {
-    return models.Post.edit(frame.data, frame.options);
-  }
-}
-```