From 6588b46e81029231f7d57081d908bb2ba1ae586c Mon Sep 17 00:00:00 2001 From: Kamen Mazdrashki Date: Fri, 10 Oct 2014 06:26:35 +0200 Subject: [PATCH 1/4] rest/api-doc: Fix text formatting so sections are rendered properly --- api/mapistore_http/source/index.rst | 38 ++++++++++++++--------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/api/mapistore_http/source/index.rst b/api/mapistore_http/source/index.rst index e68d4c8..3109537 100644 --- a/api/mapistore_http/source/index.rst +++ b/api/mapistore_http/source/index.rst @@ -584,9 +584,9 @@ Tasks "id": "b1f2726d32b44551b99f4a6adb61e112" } - :>json string id: Message identifier of the task item created - :reqheader Authorization: auth token - :statuscode 200: Ok + :>json string id: Message identifier of the task item created + :reqheader Authorization: auth token + :statuscode 200: Ok .. http:get:: /tasks/(id)/ @@ -612,9 +612,9 @@ Tasks { "id": "b1f2726d32b44551b99f4a6adb61e112", - "parent_id": "95fc55f35da743bc9450ae694f38def0", - "PidTagSubject": "My sample task", - "PidTagBody": "Sample body" + "parent_id": "95fc55f35da743bc9450ae694f38def0", + "PidTagSubject": "My sample task", + "PidTagBody": "Sample body" }, :reqheader Authorization: auth token @@ -730,9 +730,9 @@ Contacts "id": "d220314b8a374d2bbd7f43bf0819b5a0" } - :>json string id: Message identifier of the contact item created - :reqheader Authorization: auth token - :statuscode 200: Ok + :>json string id: Message identifier of the contact item created + :reqheader Authorization: auth token + :statuscode 200: Ok .. http:get:: /contacts/(id)/ @@ -758,9 +758,9 @@ Contacts { "id": "d220314b8a374d2bbd7f43bf0819b5a0", - "parent_id": "9175fe8d54da416a9cb1a946c50b7467", - "PidTagSubject": "My sample contact", - "PidTagBody": "Sample body" + "parent_id": "9175fe8d54da416a9cb1a946c50b7467", + "PidTagSubject": "My sample contact", + "PidTagBody": "Sample body" }, :reqheader Authorization: auth token @@ -860,7 +860,7 @@ Notes { "parent_id": "765dc8566f9e4baf94ee36e1b2763d50", "PidTagSubject": "My sample note", - "PidTagBody": "Sample body" + "PidTagBody": "Sample body" } **Example response**: @@ -875,9 +875,9 @@ Notes "id": "f07d68499c974a5bbffed5cc3ddcc31e" } - :>json string id: Message identifier of the note item created - :reqheader Authorization: auth token - :statuscode 200: Ok + :>json string id: Message identifier of the note item created + :reqheader Authorization: auth token + :statuscode 200: Ok .. http:get:: /notes/(id)/ @@ -903,9 +903,9 @@ Notes { "id": "f07d68499c974a5bbffed5cc3ddcc31e", - "parent_id": "765dc8566f9e4baf94ee36e1b2763d50", - "PidTagSubject": "My sample note", - "PidTagBody": "Sample body" + "parent_id": "765dc8566f9e4baf94ee36e1b2763d50", + "PidTagSubject": "My sample note", + "PidTagBody": "Sample body" }, :reqheader Authorization: auth token From d5c335dd564fc6221b9bb2f9401dd439802697f2 Mon Sep 17 00:00:00 2001 From: Kamen Mazdrashki Date: Sat, 11 Oct 2014 05:29:30 +0200 Subject: [PATCH 2/4] rest/api-doc: Add preliminary section for /mail/ service --- api/mapistore_http/source/index.rst | 164 +++++++++++++++++++++++++++- 1 file changed, 162 insertions(+), 2 deletions(-) diff --git a/api/mapistore_http/source/index.rst b/api/mapistore_http/source/index.rst index 3109537..797a01d 100644 --- a/api/mapistore_http/source/index.rst +++ b/api/mapistore_http/source/index.rst @@ -402,8 +402,168 @@ Folders Email ------- -TBD +----- + +TODO + - Define sending e-mail + - Do we need special handling for Recipients? + - Move/Copy message defintion? + + +.. http:post:: /mail/ + + :synopsis: Creates a new mail message and returns its ID. + ``parent_id`` and ``PidTagSubject``` are required. + Other message attributes are optional. + + **Example request**: + + .. sourcecode:: http + + POST /mail/ HTTP/1.1 + Host: example.com + Accept: application/json + + { + "parent_id": "c7e77cc9999908ec54ae32f1faf17e0e", + "PidTagSubject": "New mail message", + "PidTagBody": "Message text body", + "PidTagBodyHtml": "...." + } + + :json string id: Message Identifier of the message created + :reqheader Authorization: auth token + :statuscode 200: Ok + :statuscode 422: The request was well-formed but was unable + to be followed due to semantic errors + + +.. http:get:: /mail/(id)/ + + :synopsis: Retrieve all the properties of an email message + identified by `id` + + **Example request**: + + .. sourcecode:: http + + GET /mail/15924213158245d0ad631c6a41a0e7c3/ HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: application/json + + { + "id": "15924213158245d0ad631c6a41a0e7c3", + "parent_id": "cea793f236334942bdae2c1e6c83607d", + "PidTagSubject": "New mail message", + "PidTagBody": "Sample body", + "PidTagBodyHtml": "..." + }, + + :reqheader Authorization: auth token + :reqheader Accept: the response content depends on on + :mailheader:`Accept` header + :resheader Content-Type: this depends on :mailheader:`Accept` + header of the request + :statuscode 200: Ok + :statuscode 404: Item does not exist + + +.. http:put:: /mail/(id)/ + + :synopsis: Set properties on email message identified by `id` + + **Example request**: + + .. sourcecode:: http + + PUT /mail/15924213158245d0ad631c6a41a0e7c3/ HTTP/1.1 + Host: example.com + Accept: application/json + + { + "PidTagBody": "Sample body v2" + } + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 201 No Content + + :reqheader Authorization: auth token + :statuscode 201: The update was successfully applied + :statuscode 400: Bad request + + +.. http:head:: /mail/(id)/ + + :synopsis: Check if the email message identified by `id` exists + + **Example request**: + + .. sourcecode:: http + + HEAD /calendars/15924213158245d0ad631c6a41a0e7c3/ HTTP/1.1 + Host: example.com + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + + :reqheader Authorization: auth token + :statuscode 200: Ok + :statuscode 404: Item does not exist + + +.. http:delete:: /mail/(id)/ + + :synopsis: Delete the email message identified by `id` + + **Example request**: + + .. sourcecode:: http + + DELETE /mail/15924213158245d0ad631c6a41a0e7c3 HTTP/1.1 + Host: example.com + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 204 No content + + :reqheader Authorization: auth token + :statuscode 204: Ok + :statuscode 404: Item does not exist + Calendar -------- From 55b8fd7f7cd2fac4a3a886ce4d72a785ebf04ba2 Mon Sep 17 00:00:00 2001 From: Kamen Mazdrashki Date: Sat, 11 Oct 2014 05:29:59 +0200 Subject: [PATCH 3/4] rest/api-doc: White spaces fixed for better sections rendering --- api/mapistore_http/source/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/mapistore_http/source/index.rst b/api/mapistore_http/source/index.rst index 797a01d..3a60b96 100644 --- a/api/mapistore_http/source/index.rst +++ b/api/mapistore_http/source/index.rst @@ -583,7 +583,7 @@ Calendar { "parent_id": "cea793f236334942bdae2c1e6c83607d", "PidTagSubject": "My sample appointment", - "PidTagBody": "Sample body" + "PidTagBody": "Sample body" } **Example response**: @@ -626,9 +626,9 @@ Calendar { "id": "15924213158245d0ad631c6a41a0e7c3", - "parent_id": "cea793f236334942bdae2c1e6c83607d", - "PidTagSubject": "My sample appointment", - "PidTagBody": "Sample body" + "parent_id": "cea793f236334942bdae2c1e6c83607d", + "PidTagSubject": "My sample appointment", + "PidTagBody": "Sample body" }, :reqheader Authorization: auth token From 8b8d04162b9eb8850b9f873e652fe8d3cbee6e3b Mon Sep 17 00:00:00 2001 From: Kamen Mazdrashki Date: Sat, 11 Oct 2014 05:42:19 +0200 Subject: [PATCH 4/4] rest/api-doc: Update '/info/' service to add "contexts" information Contexts are basically main folders known to the backend --- api/mapistore_http/source/index.rst | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/api/mapistore_http/source/index.rst b/api/mapistore_http/source/index.rst index 3a60b96..ea3070e 100644 --- a/api/mapistore_http/source/index.rst +++ b/api/mapistore_http/source/index.rst @@ -34,13 +34,21 @@ Backend info Content-Type: application/json { - "name": "My MAPISTORE Backend", - "version": 3, - "capabilities": { - "soft_delete": true, - "...": "...", - }, - }, + "name": "My MAPISTORE Backend", + "version": 3, + "capabilities": { + "soft_delete": true, + "...": "...", + }, + "contexts": [ + { + "url": "/calendars/", + "roles": ["calendar"], + "name": "Personal Calendar", + "main_folder": true + } + ] + } :reqheader Authorization: auth token :reqheader Accept: the response content type depends on