From 8258abd6ea26e173ff01e9515e743ad8707e2602 Mon Sep 17 00:00:00 2001
From: Eugen Rochko <eugen@zeonfederated.com>
Date: Fri, 5 Oct 2018 02:35:29 +0200
Subject: [PATCH] Add media API and split API docs in two menu items

---
 config.toml                               |  7 +++-
 content/en/api/rest/apps.md               |  4 +--
 content/en/api/rest/blocks.md             |  4 +--
 content/en/api/rest/custom-emojis.md      |  4 +--
 content/en/api/rest/endorsements.md       |  4 +--
 content/en/api/rest/favourites.md         |  4 +--
 content/en/api/rest/follow-suggestions.md |  4 +--
 content/en/api/rest/instances.md          |  4 +--
 content/en/api/rest/media.md              | 43 +++++++++++++++++++++--
 content/en/api/rest/mutes.md              |  4 +--
 content/en/api/rest/reports.md            |  4 +--
 content/en/api/rest/search.md             |  4 +--
 content/en/api/rest/timelines.md          |  4 +--
 13 files changed, 69 insertions(+), 25 deletions(-)

diff --git a/config.toml b/config.toml
index 3ceca34d..3d494015 100644
--- a/config.toml
+++ b/config.toml
@@ -31,7 +31,12 @@ enableGitInfo = true
     identifier = "development"
     url = "/development/"
   [[menu.docs]]
-    name = "API"
+    name = "API Overview"
     weight = 4
     identifier = "api"
     url = "/api/"
+  [[menu.docs]]
+    name = "REST API"
+    weight = 5
+    identifier = "rest-api"
+    url = "/api/rest/"
diff --git a/content/en/api/rest/apps.md b/content/en/api/rest/apps.md
index 656c8558..e2eca584 100644
--- a/content/en/api/rest/apps.md
+++ b/content/en/api/rest/apps.md
@@ -1,8 +1,8 @@
 ---
-title: Apps API
+title: Apps
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
 
diff --git a/content/en/api/rest/blocks.md b/content/en/api/rest/blocks.md
index 2a71fcb6..e0010612 100644
--- a/content/en/api/rest/blocks.md
+++ b/content/en/api/rest/blocks.md
@@ -1,8 +1,8 @@
 ---
-title: Blocks API
+title: Blocks
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
 
diff --git a/content/en/api/rest/custom-emojis.md b/content/en/api/rest/custom-emojis.md
index 07664c0b..7d6cb36d 100644
--- a/content/en/api/rest/custom-emojis.md
+++ b/content/en/api/rest/custom-emojis.md
@@ -1,8 +1,8 @@
 ---
-title: Custom emoji API
+title: Custom emoji
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
 
diff --git a/content/en/api/rest/endorsements.md b/content/en/api/rest/endorsements.md
index 3df6ee87..5328b609 100644
--- a/content/en/api/rest/endorsements.md
+++ b/content/en/api/rest/endorsements.md
@@ -1,8 +1,8 @@
 ---
-title: Endorsements API
+title: Endorsements
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
 
diff --git a/content/en/api/rest/favourites.md b/content/en/api/rest/favourites.md
index e1c92d11..c044567f 100644
--- a/content/en/api/rest/favourites.md
+++ b/content/en/api/rest/favourites.md
@@ -1,8 +1,8 @@
 ---
-title: Favourites API
+title: Favourites
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
 
diff --git a/content/en/api/rest/follow-suggestions.md b/content/en/api/rest/follow-suggestions.md
index 49b2dca6..8b484540 100644
--- a/content/en/api/rest/follow-suggestions.md
+++ b/content/en/api/rest/follow-suggestions.md
@@ -1,8 +1,8 @@
 ---
-title: Follow suggestions API
+title: Follow suggestions
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
 
diff --git a/content/en/api/rest/instances.md b/content/en/api/rest/instances.md
index d40d8e05..d8355481 100644
--- a/content/en/api/rest/instances.md
+++ b/content/en/api/rest/instances.md
@@ -1,8 +1,8 @@
 ---
-title: Instances API
+title: Instances
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
 
diff --git a/content/en/api/rest/media.md b/content/en/api/rest/media.md
index 4c123aa2..eac016f3 100644
--- a/content/en/api/rest/media.md
+++ b/content/en/api/rest/media.md
@@ -1,7 +1,46 @@
 ---
-title: Media attachments API
+title: Media attachments
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
+
+## POST /api/v1/media
+
+Upload a media attachment that can be used with a new status.
+
+Returns [Attachment]({{< relref "entities.md#attachment" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="write write:media" version="0.0.0" >}}
+
+### Parameters
+
+|Name|Description|Required|Default|
+|----|-----------|:------:|:-----:|
+| `file` | Media to be uploaded (encoded using `multipart/form-data`) | Required ||
+| `description` | A plain-text description of the media for accessibility (max 420 chars) | Optional ||
+| `focus` | Two floating points, comma-delimited. See [focal points](#focal-points) | Optional ||
+
+## PUT /api/v1/media/:id
+
+Update a media attachment. Can only be done before the media is attached to a status.
+
+Returns [Attachment]({{< relref "entities.md#attachment" >}})
+
+### Resource information
+
+{{< api_method_info auth="Yes" user="Yes" scope="write write:media" version="0.0.0" >}}
+
+### Parameters
+
+|Name|Description|Required|Default|
+|----|-----------|:------:|:-----:|
+| `description` | A plain-text description of the media for accessibility (max 420 chars) | Optional ||
+| `focus` | Two floating points, comma-delimited. See [focal points](#focal-points) | Optional ||
+
+## Focal points
+
+Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. [See this for how to let users select focal point coordinates](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point).
diff --git a/content/en/api/rest/mutes.md b/content/en/api/rest/mutes.md
index f9fd4f4b..1d443665 100644
--- a/content/en/api/rest/mutes.md
+++ b/content/en/api/rest/mutes.md
@@ -1,8 +1,8 @@
 ---
-title: Mutes API
+title: Mutes
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
 
diff --git a/content/en/api/rest/reports.md b/content/en/api/rest/reports.md
index a4cacb15..a081880d 100644
--- a/content/en/api/rest/reports.md
+++ b/content/en/api/rest/reports.md
@@ -1,8 +1,8 @@
 ---
-title: Reports API
+title: Reports
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
 
diff --git a/content/en/api/rest/search.md b/content/en/api/rest/search.md
index 2b19eba3..b515e91c 100644
--- a/content/en/api/rest/search.md
+++ b/content/en/api/rest/search.md
@@ -1,8 +1,8 @@
 ---
-title: Search API
+title: Search
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---
 
diff --git a/content/en/api/rest/timelines.md b/content/en/api/rest/timelines.md
index 134a511e..5249d8eb 100644
--- a/content/en/api/rest/timelines.md
+++ b/content/en/api/rest/timelines.md
@@ -1,8 +1,8 @@
 ---
-title: Timelines API
+title: Timelines
 menu:
   docs:
-    parent: api
+    parent: rest-api
     weight: 10
 ---