diff --git a/doc/attachments.rst b/doc/attachments.rst index 4fa55b6..2236e67 100644 --- a/doc/attachments.rst +++ b/doc/attachments.rst @@ -1,57 +1,71 @@ ================ ``/attachments`` ================ ``POST /attachments/upload`` ============================ Upload an attachment. Returns an upload-id that can be used to attach the attachment to an object. ``POST /attachments//`` =============================================== Attach an attachment to an object with uid, found in folder uid. Fields to include are the upload-id returned from ``POST /attachment/upload``. .. NOTE:: This requires an email that is being composed also be saved off as a Draft, before the attachment can be attached to an existing object. ``GET /attachments///`` ============================================================== Retrieve information about an attachment. Note that for the attachment, this currently includes the same information as contained within the list of attachments obtained from ``////attachments``. +**Example Result** + +``GET /attachments/6c11cd1e5283576e/1D41B2DB805B93596B85F6B7BCAD5700-9EFCC9880FAF1EAB/3`` + +.. parsed-literal:: + + { + "id": "3", + "mimetype": "application\/pdf", + "size": 239932, + "filename": "doc.pdf", + "disposition": "attachment" + } + .. seealso:: * :ref:`example-retrieve-mails-with-attachments` ``GET /attachments////get`` ================================================================== Download the payload of an actual attachment. .. seealso:: * :ref:`example-retrieve-mails-with-attachments` ``PUT /attachments///`` ============================================================== Update an attachment. ``HEAD /attachments///`` =============================================================== Verify an attachment exists. ``DELETE /attachments///`` ================================================================= Delete an attachment. diff --git a/doc/contacts.rst b/doc/contacts.rst index 7492090..c22b273 100644 --- a/doc/contacts.rst +++ b/doc/contacts.rst @@ -1,46 +1,98 @@ ============= ``/contacts`` ============= ``GET /contacts//`` ======================================================= -Get the contact ``object-uid`` from ``folder-uid``. +Get the contact object properties. + +.. NOTE:: + + Obtain the folder uid from ``/folders``, and the contact uid from + ``/folders//objects`` + +**Example Result** + +``GET /contacts/6c11cd1e5283576e/0fcf492a-3dab-4ec1-99ee-119a6e517a3f`` + +.. parsed-literal:: + + { + "uid": "0fcf492a-3dab-4ec1-99ee-119a6e517a3f", + "rev": "20171018T104904Z", + "kind": "individual", + "fn": "Firstname Lastname", + "n": { + "surname": "Lastname", + "given": "Firstname" + }, + "group": { + "org": "Kolab Groupware" + }, + "url": [ "https:\/\/kolab.org" ], + "adr": [ + { + "parameters": {"type": "home"}, + "street": "Broadway Awenue 123", + "locality": "New York", + "code": "123456", + "country": "USA" + } + ], + "tel": [ + { + "parameters": {"type": "home"}, + "text": "+48 500000012" + } + ], + "email": [ + { + "parameters": {"type": "home"}, + "text": "home@kolab.org" + } + ], + "categories":[] + } ``GET /contacts///attachments`` ======================================================= List the attachments on the object, if any. +.. NOTE:: Kolab does not really support contact attachments. + ``HEAD /contacts///attachments`` ======================================================== Count the attachments on the object. Returns `X-Count` header with a numeric value. +.. NOTE:: Kolab does not really support contact attachments. + ``DELETE /contacts//`` ============================================== Delete an existing contact object. On success code 204 is returned. ``POST /contacts`` ================== Create a new contact in the default address book folder. .. NOTE:: Not yet implemented. ``POST /contacts/`` =============================== Create a new contact in specified folder. ``HEAD /contacts//`` ============================================ Check if the contact object exists. If object exists code 200 is returned, 404 otherwise. ``PUT /contacts//`` =========================================== Update an existing contact object. diff --git a/doc/events.rst b/doc/events.rst index d360dae..4cfad8d 100644 --- a/doc/events.rst +++ b/doc/events.rst @@ -1,84 +1,100 @@ =========== ``/events`` =========== ``GET /events//`` ======================================== Request an event. .. NOTE:: Obtain the folder uid from ``/folders``, and the event uid from ``/folders//objects`` **Example Result** ``GET /events/6c11cd1e5283576e/1D41B2DB805B93596B85F6B7BCAD5700-9EFCC9880FAF1EAB`` .. parsed-literal:: { "class": "PUBLIC", "created": "2015-02-05T05:26:20Z", "dtend": { "date-time": "2015-02-06T12:30:00", "parameters": { "tzid": "/kolab.org/Europe/Berlin" } }, "dtstamp": "2015-02-05T05:26:20Z", "dtstart": { "date-time": "2015-02-06T06:30:00", "parameters": { "tzid": "/kolab.org/Europe/Berlin" } }, "organizer": { "cal-address": "mailto:%3Cjeroen%40kolab.org%3E", "parameters": { "cn": "van Meeuwen, Jeroen" } }, "sequence": 0, "summary": "test", "uid": "1D41B2DB805B93596B85F6B7BCAD5700-9EFCC9880FAF1EAB" } ``GET /events///attachments`` ===================================================== List the attachments on the object, if any. +**Example Result** + +``GET /events/6c11cd1e5283576e/1D41B2DB805B93596B85F6B7BCAD5700-9EFCC9880FAF1EAB/attachments`` + +.. parsed-literal:: + + [ + { + "id": "3", + "mimetype": "application\/pdf", + "size": 239932, + "filename": "doc.pdf", + "disposition":"attachment" + } + ] + ``HEAD /events///attachments`` ====================================================== Count the attachments on the object. Returns `X-Count` header with a numeric value. ``DELETE /events//`` ============================================ Delete an existing event object. On success code 204 is returned. ``POST /events`` ================ Create a new event in the default calendar folder. .. NOTE:: Not yet implemented. ``POST /events/`` ============================= Create a new event in specified folder. ``HEAD /events//`` ========================================== Check if the event object exists. If object exists code 200 is returned, 404 otherwise. ``PUT /events//`` ========================================= Update an existing event object. diff --git a/doc/mails.rst b/doc/mails.rst index 5b9c8c8..6613c4d 100644 --- a/doc/mails.rst +++ b/doc/mails.rst @@ -1,83 +1,99 @@ ========== ``/mails`` ========== ``GET /mails//`` ========================================= Get the mail message object. **Example Result** ``GET /mails/169aad0b52725a31/112`` .. parsed-literal:: { "bcc": [], "categories": [], "cc": [], "date": "Mon, 4 Sep 2017 01:09:20 +0100", "flags": [ "seen" ], "from": { "address": "noreply_support@comodo.com", "name": "Comodo Security Services" }, "has-attach": false, "internaldate": " 4-Sep-2017 02:16:09 +0200", "message-id": "", "reply-to": [], "sender": [], "size": 2332, "subject": "Comodo Domain Validation for \*.kolab.org", "text": "Dear administrator@kolab.org,\n\nComodo has received a request (...). \n\nKind Regards,\n\nComodo Security Services\n\nComodo CA Limited - US Office \n525 Washington Blvd.\nJersey City, NJ 07310-1600\n\nComodo CA Limited - European Office\n26 Office Village,\nExchange Quay, Trafford Road,\nSalford, Manchester M5 3EQ,\nUnited Kingdom\n", "to": [ { "address": "administrator@kolab.org", "name": "administrator@kolab.org" } ], "uid": "112" } ``GET /mails///attachments`` ==================================================== List the message attachments, if any. +**Example Result** + +``GET /mails/169aad0b52725a31/112/attachments`` + +.. parsed-literal:: + + [ + { + "id": "3", + "mimetype": "application\/pdf", + "size": 239932, + "filename": "doc.pdf", + "disposition": "attachment" + } + ] + ``HEAD /mails///attachments`` ===================================================== Count the message attachments. Returns `X-Count` header with a numeric value. ``DELETE /mails//`` =========================================== Delete an existing message. On success code 204 is returned. ``POST /mails/`` ============================ Create a new message (draft) in specified folder. ``POST /mails/submit`` ====================== Send a message. ``HEAD /mails//`` ========================================= Check if the message exists. If object exists code 200 is returned, 404 otherwise. ``PUT /mails//`` ======================================== Update an existing message. diff --git a/doc/notes.rst b/doc/notes.rst index e0c6e43..a442349 100644 --- a/doc/notes.rst +++ b/doc/notes.rst @@ -1,46 +1,71 @@ ========== ``/notes`` ========== ``GET /notes//`` ======================================== -Get the note ``object-uid`` from ``folder-uid``. +Get the note object properties. + +.. NOTE:: + + Obtain the folder uid from ``/folders``, and the note uid from + ``/folders//objects`` + +**Example Result** + +``GET /notes/6c11cd1e5283576e/23a145ca-f384-4564-8754-d7ae1d2824b4`` + +.. parsed-literal:: + + { + "uid": "23a145ca-f384-4564-8754-d7ae1d2824b4", + "creation-date": "2017-10-18T11:14:22Z", + "last-modification-date": "2017-10-18T11:14:22Z", + "classification": "PUBLIC", + "summary": "This is a note", + "description": "Note body", + "categories": [ "tag" ] + } ``GET /notes///attachments`` ==================================================== List the attachments on the object, if any. +.. NOTE:: Kolab does not really support note attachments. + ``HEAD /notes///attachments`` ===================================================== Count the attachments on the object. Returns `X-Count` header with a numeric value. +.. NOTE:: Kolab does not really support note attachments. + ``DELETE /notes//`` =========================================== Delete an existing note object. On success code 204 is returned. ``POST /notes`` =============== Create a new note in the default notes folder. .. NOTE:: Not yet implemented. ``POST /notes/`` ============================ Create a new note in specified folder. ``HEAD /notes//`` ========================================= Check if the note object exists. If object exists code 200 is returned, 404 otherwise. ``PUT /notes//`` ======================================== Update an existing note object. diff --git a/doc/tasks.rst b/doc/tasks.rst index 9d29c4c..e6e871b 100644 --- a/doc/tasks.rst +++ b/doc/tasks.rst @@ -1,46 +1,93 @@ ========== ``/tasks`` ========== ``GET /tasks//`` ======================================== -Get the task ``object-uid`` from ``folder-uid``. +Get the task object properties. + +.. NOTE:: + + Obtain the folder uid from ``/folders``, and the task uid from + ``/folders//objects`` + +**Example Result** + +``GET /tasks/6c11cd1e5283576e/631766755B73A29579871195D9326286-8FE68B2E68E1B348`` + +.. parsed-literal:: + + { + "uid": "631766755B73A29579871195D9326286-8FE68B2E68E1B348", + "created": "2017-10-18T11:19:06Z", + "dtstamp": "2017-10-18T11:19:06Z", + "sequence": 0, + "class": "PUBLIC", + "due": "2017-10-20", + "rrule": { + "recur": {"freq": "DAILY"} + }, + "summary": "Simple Task", + "description": "This is task description", + "percent-complete": 45, + "organizer": { + "parameters": {"cn": "Aleksander Machniak"}, + "cal-address": "mailto:%3Ctest%40alec.pl%3E" + }, + "categories": [ "tag" ] + } ``GET /tasks///attachments`` ==================================================== List the attachments on the object, if any. +**Example Result** + +``GET /tasks/6c11cd1e5283576e/631766755B73A29579871195D9326286-8FE68B2E68E1B348/attachments`` + +.. parsed-literal:: + + [ + { + "id": "3", + "mimetype": "application\/pdf", + "size": 239932, + "filename": "doc.pdf", + "disposition": "attachment" + } + ] + ``HEAD /tasks///attachments`` ===================================================== Count the attachments on the object. Returns `X-Count` header with a numeric value. ``DELETE /tasks//`` =========================================== Delete an existing task object. On success code 204 is returned. ``POST /tasks`` =============== Create a new task in the default tasks folder. .. NOTE:: Not yet implemented. ``POST /tasks/`` ============================ Create a new task in specified folder. ``HEAD /tasks//`` ========================================= Check if the task object exists. If object exists code 200 is returned, 404 otherwise. ``PUT /tasks//`` ======================================== Update an existing task object.