From e77cd9cf7ef14d14165a5013155ac39d8b13cd78 Mon Sep 17 00:00:00 2001
From: Marcel Cruz <12413903+marcelscruz@users.noreply.github.com>
Date: Fri, 10 May 2024 11:17:28 +0200
Subject: [PATCH] Add API instructions

---
 API.md    | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  1 +
 2 files changed, 73 insertions(+)
 create mode 100644 API.md

diff --git a/API.md b/API.md
new file mode 100644
index 00000000..ea9300c0
--- /dev/null
+++ b/API.md
@@ -0,0 +1,72 @@
+# API
+
+This repository auto-generates the `/db` folder after each commit to `main`. The folder includes two files:
+
+`categories.json` - A list of all categories
+
+`resources.json` - A list of all APIs
+
+You can then use [Octokit](https://github.com/octokit) to fetch the data from the `db` folder.
+
+Here's a minimal snippet on how to accomplish that:
+
+```ts
+import { Octokit } from 'octokit'
+
+async function fetchResources(file: string) {
+    const octokit = new Octokit({ auth: process.env.GITHUB_ACCESS_TOKEN })
+
+    const { data } = await octokit.rest.repos.getContent({
+        owner: 'marcelscruz',
+        repo: 'public-apis',
+        path: `/db/${file}.json`,
+    })
+
+    if (data.download_url) {
+        const result = await fetch(data.download_url)
+
+        if (!result.ok) {
+            throw new Error(`Unexpected response ${result.statusText}`)
+        }
+
+        return await result.json()
+    } else {
+        throw new Error('Download URL not found')
+    }
+}
+```
+
+The response will be an object with the following structure:
+
+`categories.json`:
+
+```ts
+{
+    "count": number,
+    "entries": [
+        {
+            "name": string,
+            "slug": string
+        }
+    ]
+}
+```
+
+`resources.json`:
+
+```ts
+{
+    "count": number,
+    "entries": [
+        {
+            "API": string,
+            "Auth": string,
+            "Category": string,
+            "Cors": string,
+            "Description": string,
+            "HTTPS": boolean,
+            "Link": string,
+        }
+    ]
+}
+```
diff --git a/README.md b/README.md
index 136b65bb..3238e285 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,7 @@
 <div align="center">
     <sub>The Project</sub>
     <br />
+    <a href="API.md">API</a> •
     <a href="CONTRIBUTING.md">Contributing Guide</a> •
     <!-- Let's re-added this API once it starts using the APIs from this repository -->
     <!-- <a href="https://github.com/davemachado/public-api">API for this project</a> • -->