From cb9ed818f6207a0131090e338165ceac5a121082 Mon Sep 17 00:00:00 2001
From: Eugen Rochko <eugen@zeonfederated.com>
Date: Fri, 5 Oct 2018 00:59:57 +0200
Subject: [PATCH] Add documentation about timelines API

---
 content/en/api/rest/timelines.md              | 84 +++++++++++++++++++
 .../shortcodes/api_dynamic_pagination.html    |  1 +
 layouts/shortcodes/api_method_info.html       | 28 +++++++
 layouts/shortcodes/api_pagination.html        |  1 +
 4 files changed, 114 insertions(+)
 create mode 100644 layouts/shortcodes/api_dynamic_pagination.html
 create mode 100644 layouts/shortcodes/api_method_info.html
 create mode 100644 layouts/shortcodes/api_pagination.html

diff --git a/content/en/api/rest/timelines.md b/content/en/api/rest/timelines.md
index cdd3fe7..81d020f 100644
--- a/content/en/api/rest/timelines.md
+++ b/content/en/api/rest/timelines.md
@@ -5,3 +5,87 @@ menu:
     parent: api
     weight: 10
 ---
+
+## GET /api/v1/timelines/home
+
+Returns array of [Status]({{< relref "entities.md#status" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="0.0.0" >}}
+
+### Parameters
+
+|Name|Description|Required|Default|
+|----|-----------|:------:|:-----:|
+| `max_id` | Return results older than ID | Optional ||
+| `since_id` | Return results newer than ID | Optional ||
+| `limit` | Maximum number of results | Optional | 20 |
+
+### Pagination
+
+{{< api_dynamic_pagination >}}
+
+## GET /api/v1/timelines/public
+
+Returns array of [Status]({{< relref "entities.md#status" >}})
+
+### Resource information
+
+{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
+
+### Parameters
+
+|Name|Description|Required|Default|
+|----|-----------|:------:|:-----:|
+| `local` | Only local statuses | Optional ||
+| `only_media` | Only statuses with media attachments | Optional ||
+| `max_id` | Return results older than ID | Optional ||
+| `since_id` | Return results newer than ID | Optional ||
+| `limit` | Maximum number of results | Optional | 20 |
+
+### Pagination
+
+{{< api_dynamic_pagination >}}
+
+## GET /api/v1/timelines/tag/:hashtag
+
+Returns array of [Status]({{< relref "entities.md#status" >}})
+
+### Resource information
+
+{{< api_method_info auth="No" user="No" scope="read read:statuses" version="0.0.0" >}}
+
+### Parameters
+
+|Name|Description|Required|Default|
+|----|-----------|:------:|:-----:|
+| `local` | Only local statuses | Optional ||
+| `only_media` | Only statuses with media attachments | Optional ||
+| `max_id` | Return results older than ID | Optional ||
+| `since_id` | Return results newer than ID | Optional ||
+| `limit` | Maximum number of results | Optional | 20 |
+
+### Pagination
+
+{{< api_dynamic_pagination >}}
+
+## GET /api/v1/timelines/list/:list_id
+
+Returns array of [Status]({{< relref "entities.md#status" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="read read:statuses" version="0.0.0" >}}
+
+### Parameters
+
+|Name|Description|Required|Default|
+|----|-----------|:------:|:-----:|
+| `max_id` | Get a list of statuses with ID less than this value | Optional ||
+| `since_id` | Get a list of statuses with ID greater than this value | Optional ||
+| `limit` | Maximum number of statuses to return | Optional | 20 |
+
+### Pagination
+
+{{< api_dynamic_pagination >}}
diff --git a/layouts/shortcodes/api_dynamic_pagination.html b/layouts/shortcodes/api_dynamic_pagination.html
new file mode 100644
index 0000000..c7d01f9
--- /dev/null
+++ b/layouts/shortcodes/api_dynamic_pagination.html
@@ -0,0 +1 @@
+<p>This API returns Link headers containing links to the next and previous page. However, the links can also be constructed dynamically using query params.</p>
diff --git a/layouts/shortcodes/api_method_info.html b/layouts/shortcodes/api_method_info.html
new file mode 100644
index 0000000..d5db0b9
--- /dev/null
+++ b/layouts/shortcodes/api_method_info.html
@@ -0,0 +1,28 @@
+<table>
+  <tbody>
+    <tr>
+      <th style="text-align: left">Response format</th>
+      <td>JSON</td>
+    </tr>
+
+    <tr>
+      <th style="text-align: left">Requires authentication</th>
+      <td>{{ .Get "auth" }}</td>
+    </tr>
+
+    <tr>
+      <th style="text-align: left">Requires user</th>
+      <td>{{ .Get "user" }}</td>
+    </tr>
+
+    <tr>
+      <th style="text-align: left">Scope</th>
+      <td><code>{{ .Get "scope" }}</code></td>
+    </tr>
+
+    <tr>
+      <th style="text-align: left">Available since</th>
+      <td>{{ .Get "version" }}</td>
+    </tr>
+  </tbody>
+</table>
diff --git a/layouts/shortcodes/api_pagination.html b/layouts/shortcodes/api_pagination.html
new file mode 100644
index 0000000..e0263e7
--- /dev/null
+++ b/layouts/shortcodes/api_pagination.html
@@ -0,0 +1 @@
+<p>This API returns Link headers containing links to the next and previous page. Since it is using an internal ID, <strong>it is impossible to dynamically generate query parameters to paginate</strong>. You must rely on the Link header.</p>