From a006bb16354c6dd4cc5803509daa1742ffc5bace Mon Sep 17 00:00:00 2001 From: Frederik Gladhorn Date: Mon, 30 Dec 2013 14:24:00 +0100 Subject: Improve and share client docs Change-Id: Ib089f9418395c44ab937f65afe710b7fd5809689 Reviewed-by: Mitch Curtis --- doc/shared/client-create.qdocinc | 26 ++++++++++++++++++++++ doc/shared/client-downloadUrl.qdocinc | 0 doc/shared/client-fullTextSearch.qdocinc | 0 doc/shared/client-query.qdocinc | 37 ++++++++++++++++++++++++++++++++ doc/shared/client-remove.qdocinc | 16 ++++++++++++++ doc/shared/client-update.qdocinc | 28 ++++++++++++++++++++++++ doc/shared/client-uploadFile.qdocinc | 0 doc/shared/model-append.qdocinc | 2 +- 8 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 doc/shared/client-create.qdocinc create mode 100644 doc/shared/client-downloadUrl.qdocinc create mode 100644 doc/shared/client-fullTextSearch.qdocinc create mode 100644 doc/shared/client-query.qdocinc create mode 100644 doc/shared/client-remove.qdocinc create mode 100644 doc/shared/client-update.qdocinc create mode 100644 doc/shared/client-uploadFile.qdocinc (limited to 'doc') diff --git a/doc/shared/client-create.qdocinc b/doc/shared/client-create.qdocinc new file mode 100644 index 0000000..abf060d --- /dev/null +++ b/doc/shared/client-create.qdocinc @@ -0,0 +1,26 @@ +\brief Insert a new \a object into the database. + +The returned \l EnginioReply indicates the success of the object creation. +The object becomes available from the backend if it finishes without errors. + +\a operation determines the kind of object created. For example a regular object +or a user or usergroup. +By default, \l Enginio::ObjectOperation is used and regular objects created. +\note that the \tt objectType is required for regular objects and has to begin with +\tt {"objects."}. + +The JSON for the object that will be created must follow this structure: +\code +{ + "objectType": "object.myType", + "name" : "A thing", + "price" : "5", +} +\endcode +Where only the \tt objectType property is required and \tt name and \tt price +are examples of custom properties. + +Users and all kinds of other objects are created the same way but do not require any +\tt objectType. + +\sa EnginioReply, query(), update(), remove(), Enginio::Operation diff --git a/doc/shared/client-downloadUrl.qdocinc b/doc/shared/client-downloadUrl.qdocinc new file mode 100644 index 0000000..e69de29 diff --git a/doc/shared/client-fullTextSearch.qdocinc b/doc/shared/client-fullTextSearch.qdocinc new file mode 100644 index 0000000..e69de29 diff --git a/doc/shared/client-query.qdocinc b/doc/shared/client-query.qdocinc new file mode 100644 index 0000000..1c4499a --- /dev/null +++ b/doc/shared/client-query.qdocinc @@ -0,0 +1,37 @@ +\brief Query the database + +The \a query is an object containing the actual query to the backend. +The query will be run on the \a operation part of the backend. + +The \a query has to contain an "objectType" which has to point to a type defined +in the backend. Optionally, it can also contain: +\list +\li query - describes how objects are queried, allows filtering of results. See {https://engin.io/documentation/rest/parameters/queries} +{JSON query structure} +\li limit - limits how many objects the server should return (default value is \c 100). +\li offset - how many objects the server should skip from the beginning of the returned results. Note that the server keeps the data +in random order so that usage of offset implies using \c sort as well. +\li sort - describes how results are sorted. See \l{https://engin.io/documentation/rest/parameters/sort}{JSON sort request structure} +\li count - if the \c count is set, the server will return only count of matching objects +\li include - describes which other objects are included in the response. See \l{https://engin.io/documentation/rest/parameters/include} +{JSON include structure} +\endlist + +The JSON to list all objects of type "objects.image": +\code +{ + "objectType": "objects.image" +} +\endcode + +An example using \tt include to get \tt file references and with a query parameter that +limits the results to only those objects where the reference is valid: +\code +{ + "objectType": "objects.image", + "include": {"file": {}}, + "query" : { "file": { "$ne": null } } +} +\endcode + +\sa EnginioReply, create(), update(), remove() diff --git a/doc/shared/client-remove.qdocinc b/doc/shared/client-remove.qdocinc new file mode 100644 index 0000000..995554c --- /dev/null +++ b/doc/shared/client-remove.qdocinc @@ -0,0 +1,16 @@ +\brief Remove an object from the database. + +The \a object that is to be removed is identified by its object ID and if it is a regular object also \tt objectType. + +The JSON that identfies an object looks like this: +\code +{ + "objectType": "objects.images", + "id": "52b1a94b5a3d8b15b1037ff5" +} +\endcode + +The \a operation is the area from which the object gets removed. +It defaults to \l Enginio::ObjectOperation to remove regular objects by default. + +\sa EnginioReply, create(), query(), update() diff --git a/doc/shared/client-update.qdocinc b/doc/shared/client-update.qdocinc new file mode 100644 index 0000000..f1d0874 --- /dev/null +++ b/doc/shared/client-update.qdocinc @@ -0,0 +1,28 @@ +\brief Update an object in the database. + +The \a operation is the area in which the \a object gets updated. It defaults to \l Enginio::ObjectOperation +to update regular objects by default. + +To change the name property of an object to "New Name", use the following JSON: +\code +{ + "id": "objectId", + "objectType": "objects.objectType", + "name": "New Name" +} +\endcode + +All other existing properties of the object are not affected by the update. + +To update the access control list of an object, use the following JSON: +\code +{ + "id": "objectId", + "objectType": "objects.objectType", + "access": { "read": ["id": "userId", "objectTypes": "users"], + "update": ["id": "userId", "objectTypes": "users"], + "admin": ["id": "userId", "objectTypes": "users"] } +} +\endcode + +\sa EnginioReply, create(), query(), remove() diff --git a/doc/shared/client-uploadFile.qdocinc b/doc/shared/client-uploadFile.qdocinc new file mode 100644 index 0000000..e69de29 diff --git a/doc/shared/model-append.qdocinc b/doc/shared/model-append.qdocinc index 65f8314..cf1bb5d 100644 --- a/doc/shared/model-append.qdocinc +++ b/doc/shared/model-append.qdocinc @@ -1,4 +1,4 @@ -\brief Add a new object to the model and database. +\brief Add a new \a object to the model and database. This function appends the new object to the local model cache and makes an asynchronous request to the backend. -- cgit v1.2.1