From 4fb6ddfe06164c211f22e69fdec0b248bc61f6b4 Mon Sep 17 00:00:00 2001
From: Douwe Maan <douwe@gitlab.com>
Date: Wed, 29 Jul 2015 15:40:08 +0200
Subject: Add ability to manage user email addresses via the API.

---
 doc/api/users.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)

(limited to 'doc/api/users.md')

diff --git a/doc/api/users.md b/doc/api/users.md
index 5dca77b5c7b..9ac55d3f09e 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -397,6 +397,138 @@ Parameters:
 
 Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found.
 
+## List emails
+
+Get a list of currently authenticated user's emails.
+
+```
+GET /user/emails
+```
+
+```json
+[
+  {
+    "id": 1,
+    "email": "email@example.com"
+  },
+  {
+    "id": 3,
+    "email": "email2@example.com"
+  }
+]
+```
+
+Parameters:
+
+- **none**
+
+## List emails for user
+
+Get a list of a specified user's emails. Available only for admin
+
+```
+GET /users/:uid/emails
+```
+
+Parameters:
+
+- `uid` (required) - id of specified user
+
+## Single SSH key
+
+Get a single key.
+
+```
+GET /user/emails/:id
+```
+
+Parameters:
+
+- `id` (required) - The ID of an SSH key
+
+```json
+{
+  "id": 1,
+  "email": "email@example.com"
+}
+```
+
+## Add email
+
+Creates a new email owned by the currently authenticated user.
+
+```
+POST /user/emails
+```
+
+Parameters:
+
+- `email` (required) - email address
+
+```json
+{
+  "id": 4,
+  "email": "email@example.com"
+}
+```
+
+Will return created key with status `201 Created` on success. If an
+error occurs a `400 Bad Request` is returned with a message explaining the error:
+
+```json
+{
+  "message": {
+    "email": [
+      "has already been taken"
+    ]
+  }
+}
+```
+
+## Add email for user
+
+Create new email owned by specified user. Available only for admin
+
+```
+POST /users/:id/emails
+```
+
+Parameters:
+
+- `id` (required)    - id of specified user
+- `email` (required) - email address
+
+Will return created key with status `201 Created` on success, or `404 Not found` on fail.
+
+## Delete email for current user
+
+Deletes email owned by currently authenticated user.
+This is an idempotent function and calling it on a email that is already deleted
+or not available results in `200 OK`.
+
+```
+DELETE /user/emails/:id
+```
+
+Parameters:
+
+- `id` (required) - email ID
+
+## Delete email for given user
+
+Deletes email owned by a specified user. Available only for admin.
+
+```
+DELETE /users/:uid/emails/:id
+```
+
+Parameters:
+
+- `uid` (required) - id of specified user
+- `id` (required)  - email ID
+
+Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found.
+
 ## Block user
 
 Blocks the specified user.  Available only for admin.
-- 
cgit v1.2.1


From 1c7a8b8c27398250983bf4329007f6971df65f34 Mon Sep 17 00:00:00 2001
From: Douwe Maan <douwe@gitlab.com>
Date: Thu, 30 Jul 2015 11:41:59 +0200
Subject: Fix docs

---
 doc/api/users.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'doc/api/users.md')

diff --git a/doc/api/users.md b/doc/api/users.md
index 9ac55d3f09e..7ba2db248ff 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -434,9 +434,9 @@ Parameters:
 
 - `uid` (required) - id of specified user
 
-## Single SSH key
+## Single email
 
-Get a single key.
+Get a single email.
 
 ```
 GET /user/emails/:id
@@ -444,7 +444,7 @@ GET /user/emails/:id
 
 Parameters:
 
-- `id` (required) - The ID of an SSH key
+- `id` (required) - email ID
 
 ```json
 {
@@ -472,7 +472,7 @@ Parameters:
 }
 ```
 
-Will return created key with status `201 Created` on success. If an
+Will return created email with status `201 Created` on success. If an
 error occurs a `400 Bad Request` is returned with a message explaining the error:
 
 ```json
@@ -498,7 +498,7 @@ Parameters:
 - `id` (required)    - id of specified user
 - `email` (required) - email address
 
-Will return created key with status `201 Created` on success, or `404 Not found` on fail.
+Will return created email with status `201 Created` on success, or `404 Not found` on fail.
 
 ## Delete email for current user
 
@@ -527,7 +527,7 @@ Parameters:
 - `uid` (required) - id of specified user
 - `id` (required)  - email ID
 
-Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found.
+Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found.
 
 ## Block user
 
-- 
cgit v1.2.1