From: Christian Weiske Date: Thu, 8 Apr 2021 15:56:04 +0000 (+0200) Subject: Family sharing API doc X-Git-Url: https://git.cweiske.de/tolino-api-docs.git/commitdiff_plain/08de91cc38105d644e266608827d903eea421085 Family sharing API doc --- diff --git a/README.rst b/README.rst index fee2390..9f53f67 100644 --- 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 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 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 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 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 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 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 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 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 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 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 b02992a..ee3d0bf 100644 --- 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: