Family sharing API doc

diff --git a/README.rst b/README.rst
index fee2390ef547b2143701f10707dc8334b976973b..9f53f6741758f0e4e6ec0a53c1594fe92f02ad4b 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -42,8 +42,13 @@ API calls
 .. include:: api/pageplace.bosh-bosh-rest-v2-registerhw.rst
 .. include:: api/pageplace.bosh-bosh-rest-v2-resellerconfig.rst
 .. include:: api/pageplace.family-v1-family.rst
+.. include:: api/pageplace.family-v1-family-post.rst
+.. include:: api/pageplace.family-v1-family-members-xxx.rst
 .. include:: api/pageplace.family-v1-myself.rst
+.. include:: api/pageplace.family-v1-myself-put.rst
 .. include:: api/pageplace.family-v1-shares.rst
+.. include:: api/pageplace.family-v1-shares-delete.rst
+.. include:: api/pageplace.family-v1-shares-post.rst
 .. include:: api/pageplace.inventory-v2-inventory.rst
 .. include:: api/thalia-auth-oauth2-authorize.rst
 .. include:: api/thalia-auth-oauth2-token-post.rst

diff --git a/api/pageplace.family-v1-family-members-xxx.rst b/api/pageplace.family-v1-family-members-xxx.rst
new file mode 100644 (file)
index 0000000..0f7515a
--- /dev/null
+++ b/api/pageplace.family-v1-family-members-xxx.rst
@@ -0,0 +1,41 @@
+============================================================
+``DELETE https://family.pageplace.de/v1/family/members/xxx``
+============================================================
+
+Remove someone from own family.
+
+
+Request
+=======
+Header
+  See `family v1 header set`_.
+
+``xxx``
+  Family member ID. Example: ``90498``
+
+
+Response
+========
+Success
+-------
+HTTP status code ``200 OK``.
+
+No response body (status code thus should be 204).
+
+
+Removing non-member
+-------------------
+Status code: ``401 Unauthorized``. No response body.
+
+
+Missing OAuth token
+-------------------
+Status code: ``401 Unauthorized``. Body::
+
+    {
+        "timestamp":"2021-04-08T15:52:13.186+00:00",
+        "status":403,
+        "error":"Forbidden",
+        "message":"",
+        "path":"/v1/family/members/90490"
+    }

diff --git a/api/pageplace.family-v1-family-post.response.json b/api/pageplace.family-v1-family-post.response.json
new file mode 100644 (file)
index 0000000..6870d27
--- /dev/null
+++ b/api/pageplace.family-v1-family-post.response.json
@@ -0,0 +1,17 @@
+{
+    "maxMembers": 6,
+    "members": [
+        {
+            "membershipId": 67675,
+            "nickname": "devnew"
+        },
+        {
+            "membershipId": 90498,
+            "nickname": "Ebookde"
+        },
+        {
+            "membershipId": 67674,
+            "nickname": "oldtest"
+        }
+    ]
+}

diff --git a/api/pageplace.family-v1-family-post.rst b/api/pageplace.family-v1-family-post.rst
new file mode 100644 (file)
index 0000000..413fc5b
--- /dev/null
+++ b/api/pageplace.family-v1-family-post.rst
@@ -0,0 +1,36 @@
+==============================================
+``POST https://family.pageplace.de/v1/family``
+==============================================
+
+Add someone to a family.
+
+To add a family member, an OAuth token with scope ``family`` needs to be
+obtained.
+
+
+Request
+=======
+Header
+  See `family v1 header set`_.
+
+Body
+  JSON encoded object.
+
+  ``resellerId``
+    Example: ``81``
+  ``token``
+    Example: ``eyJhbGciOiJSUzUxMiJ9.eyJpc3MiOiJ3...hGCE8Yc6g``
+
+
+Response
+========
+HTTP status code ``200 OK``.
+
+All family members are returned.
+
+Family with 3 members
+---------------------
+Example:
+
+.. include:: pageplace.family-v1-family-post.response.json
+   :code:

diff --git a/api/pageplace.family-v1-myself-put.request.json b/api/pageplace.family-v1-myself-put.request.json
new file mode 100644 (file)
index 0000000..55afb59
--- /dev/null
+++ b/api/pageplace.family-v1-myself-put.request.json
@@ -0,0 +1,3 @@
+{
+    "nickname": "devnew"
+}

diff --git a/api/pageplace.family-v1-myself-put.response.json b/api/pageplace.family-v1-myself-put.response.json
new file mode 100644 (file)
index 0000000..749d5d2
--- /dev/null
+++ b/api/pageplace.family-v1-myself-put.response.json
@@ -0,0 +1,4 @@
+{
+    "membershipId": 67675,
+    "nickname": "devnew"
+}

diff --git a/api/pageplace.family-v1-myself-put.rst b/api/pageplace.family-v1-myself-put.rst
new file mode 100644 (file)
index 0000000..248e857
--- /dev/null
+++ b/api/pageplace.family-v1-myself-put.rst
@@ -0,0 +1,28 @@
+=============================================
+``PUT https://family.pageplace.de/v1/myself``
+=============================================
+
+Rename myself in the family.
+
+
+Request
+=======
+Header
+  See `family v1 header set`_.
+
+Body
+  JSON-Encoded. Structure:
+
+  ``nickname``
+    New own name
+
+
+.. include:: pageplace.family-v1-myself-put.request.json
+   :code:
+
+Response
+========
+HTTP status code ``200 OK``.
+
+.. include:: pageplace.family-v1-myself-put.response.json
+   :code:

diff --git a/api/pageplace.family-v1-shares-delete.rst b/api/pageplace.family-v1-shares-delete.rst
new file mode 100644 (file)
index 0000000..bc2b13b
--- /dev/null
+++ b/api/pageplace.family-v1-shares-delete.rst
@@ -0,0 +1,26 @@
+================================================
+``DELETE https://family.pageplace.de/v1/shares``
+================================================
+
+Un-share a book.
+
+
+Request
+=======
+Header
+  See `family v1 header set`_.
+GET parameters
+  ``pubid``
+    Example: ``DT0400.9783641243609_A40398678``
+  ``receiver``
+    Example: ``67674``
+  ``sharer``
+    Example: ``67675``
+
+No body.
+
+Response
+========
+HTTP status code ``200 OK``.
+
+No response body (thus status code should better be 204).

diff --git a/api/pageplace.family-v1-shares-post.request.json b/api/pageplace.family-v1-shares-post.request.json
new file mode 100644 (file)
index 0000000..8b7fb69
--- /dev/null
+++ b/api/pageplace.family-v1-shares-post.request.json
@@ -0,0 +1,8 @@
+{
+    "shares": [
+        {
+            "publicationId": "DT0400.9783641243609_A40398678",
+            "receiver": "67674"
+        }
+    ]
+}

diff --git a/api/pageplace.family-v1-shares-post.rst b/api/pageplace.family-v1-shares-post.rst
new file mode 100644 (file)
index 0000000..4027692
--- /dev/null
+++ b/api/pageplace.family-v1-shares-post.rst
@@ -0,0 +1,32 @@
+==============================================
+``POST https://family.pageplace.de/v1/shares``
+==============================================
+
+Share a book with a family member
+
+
+Request
+=======
+Header
+  See `family v1 header set`_.
+
+Body
+  JSON-Encoded. Structure:
+
+  ``shares``
+    Array of books to share (each an object)
+
+    ``publicationId``
+      Example: ``DT0400.9783641243609_A40398678``
+    ``receiver``
+      Example: ``67674``
+
+
+.. include:: pageplace.family-v1-shares-post.request.json
+   :code:
+
+Response
+========
+HTTP status code ``200 OK``.
+
+No response body (thus status code should better be 204).

diff --git a/api/pageplace.family-v1-shares.response.json b/api/pageplace.family-v1-shares.response.json
new file mode 100644 (file)
index 0000000..d4ba2fa
--- /dev/null
+++ b/api/pageplace.family-v1-shares.response.json
@@ -0,0 +1,44 @@
+[
+  {
+    "type": "RECEIVED",
+    "publicationId": "DT0400.9783739616957_A25832535",
+    "sharer": {
+      "membershipId": 67674,
+      "nickname": "oldtest"
+    },
+    "receivers": [
+      {
+        "membershipId": 67675,
+        "nickname": "devnew"
+      }
+    ]
+  },
+  {
+    "type": "SHARED",
+    "publicationId": "DT0400.9783739673417_A27522964",
+    "sharer": {
+      "membershipId": 67675,
+      "nickname": "devnew"
+    },
+    "receivers": [
+      {
+        "membershipId": 67674,
+        "nickname": "oldtest"
+      }
+    ]
+  },
+  {
+    "type": "SHARED",
+    "publicationId": "DT0400.9783641243609_A40398678",
+    "sharer": {
+      "membershipId": 67675,
+      "nickname": "devnew"
+    },
+    "receivers": [
+      {
+        "membershipId": 67674,
+        "nickname": "oldtest"
+      }
+    ]
+  }
+]

diff --git a/api/pageplace.family-v1-shares.rst b/api/pageplace.family-v1-shares.rst
index b02992a8a2b44ceeda4227c20b1a9a8c79740454..ee3d0bf0cdf435fe54f617471397e0e1d290b80a 100644 (file)
--- a/api/pageplace.family-v1-shares.rst
+++ b/api/pageplace.family-v1-shares.rst
@@ -29,5 +29,5 @@ Family members
 --------------
 Example:
 
-.. include:: pageplace.family-v1-shares.response-2books.json
+.. include:: pageplace.family-v1-shares.response.json
    :code: