examples and search parameter explained

sphinx/source/technical/api_parameters_03.rst

@@ -275,10 +275,125 @@ API parameters 0.3
    * - Format
      - string, multiple
    * - Description
-     - Search request with AND/OR logic
+     - Search request with complex AND/OR logic
    * - Values
      -
 
+The search parameter provides a tool to filter and search the request with logical operators.
+
+**Example**
+    The search parameter takes a JSON as value. A key has to be a *filterable category* followed by a list/array.
+    This list need to have again JSON values as items. There can be multiple search parameters. E.g:
+
+.. code-block::
+
+    {domain}/api/{api version}/{endpoint}?search={
+        "typeID": [{"operator": "equal", "values": [123456]}],
+        "typeName": [{"operator": "like", "values": ["Chain", "Bracelet", "Amule"], "logicalOperator": "and"}]
+    }& search = {
+        "typeName": [{"operator": "equal", "values": ["Gold"]}],
+        "beginFrom": [{"operator": "lesserThan", "values": ["0850-05-12"],"logicalOperator": "and"}]}
+
+Every JSON in a search parameter field is logical connected with AND. E.g:
+
+.. code-block::
+
+    ?search={A:[{X}, {Y}], B: [M]} => Entities containing A(X and Y) and B(M)
+
+To build an search start with following parameter:
+
+    ``?search={}``
+
+Now a `categories`_ after which the results are search, has to be selected:
+
+    ``?search={"typeName"}``
+
+After the `categories`_ are selected, next make a list with possible multiple JSONs (JSONs are connected with *OR*)
+
+    ``?search={"typeName": [{},{}]}``
+
+Next a list of `values`_ has to be provided:
+
+    ``?search={"typeName": [{"values": ["Gold", "Silver"]}]}``
+
+Then an `operators`_ has to be selected, how the `values`_ should be treated:
+
+    ``?search={"typeName": [{"operator": "equal", "values": ["Gold", "Silver"]}]}``
+
+At last a `logical`_ operator can be assigned, if the values will be treated with *OR* or *AND*:
+
+    ``?search={"typeName": [{"operator": "equal", "values": ["Gold", "Silver"], "logicalOperator": "and"}]}``
+
+.. _categories:
+
+Filterable categories
+^^^^^^^^^^^^^^^^^^^^^
+
+.. hlist::
+   :columns: 5
+
+   - entityName
+   - entityDescription
+   - entityAliases
+   - entityCidocClass
+   - entitySystemClass
+   - entityID
+   - typeID
+   - valueTypeID
+   - typeIDWithSubs
+   - typeName
+   - beginFrom
+   - beginTo
+   - endFrom
+   - endTo
+   - relationToID
+
+.. _values:
+
+Values
+^^^^^^
+
+Values has to be a list of items. The items can be either a string, an integer or a tuple (see Note). Strings need to
+be marked with "" or '', while integers doesn't allow this.
+
+*Note*: the category valueTypeID can search for values of a type ID. But it takes one or more two valued Tuple as list
+entry: (x,y). x is the type id and y is the searched value. This can be an int or a float, e.g:
+
+     ``{"operator":"lesserThan","values":[(3142,543.3)],"logicalOperator":"and"}``
+
+.. _operators:
+
+Compare operators
+^^^^^^^^^^^^^^^^^
+
+.. hlist::
+   :columns: 4
+
+   - equal
+   - notEqual
+   - like [1]_
+   - greaterThan [2]_
+   - greaterThanEqual [2]_
+   - lesserThan [2]_
+   - lesserThanEqual [2]_
+
+The compare operators work like the mathematical operators.
+equal x=y, notEqual x!=y, greaterThan x>y , greaterThanEqual x>=y, lesserThan x<y, lesserThanEqual x<=y.
+The like operator searches for occurrence of the string, so a match can also occur in the middle of a word.
+
+.. [1] Only for string based categories
+.. [2] Only for beginFrom, beginTo, endFrom, endTo, valueTypeID
+
+.. _logical:
+
+Logical operators
+^^^^^^^^^^^^^^^^^
+
+Not mandatory, *OR* is the default value. Logical operators handles, if the `values`_ are treated as *OR* or *AND*.
+
+ ``and, or``
+
+
 .. _show-para-0.3:
 
 .. list-table:: **show**

sphinx/source/technical/api_version_03.rst

@@ -20,6 +20,9 @@ Places format (LPF). Alternatively, Linked Open Art (LOUD), GeoJSON or RDFs, der
 :ref:`download-para-0.3` :ref:`export-para-0.3` :ref:`format-para-0.3` :ref:`show-para-0.3`
 ======================== ====================== ====================== ====================
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/entity/4840?format=loud
+
 Query
 *****
 
@@ -50,6 +53,8 @@ query; each request has to be a new parameter.
   :ref:`sort-para-0.3`   :ref:`type_id-para-0.3`
 ======================== ======================= ======================== ============================= ====================== ======================
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/query?cidoc_classes=E18&cidoc_classes=E31&system_classes=person&limit=120
 
 Multiple entities
 *****************
@@ -74,6 +79,9 @@ Retrieves a JSON list of entities based on their CIDOC CRM class [1]_ [2]_
   :ref:`sort-para-0.3`   :ref:`type_id-para-0.3`
 ======================== ======================= ======================== ============================= ====================== ======================
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/cidoc_class/E18
+
 Entities linked to entity
 """""""""""""""""""""""""
 
@@ -91,6 +99,9 @@ Used to retrieve a JSON list of entities linked to the entity with the stated **
   :ref:`sort-para-0.3`   :ref:`type_id-para-0.3`
 ======================== ======================= ======================== ============================= ====================== ======================
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/entities_linked_to_entity/4840
+
 Latest
 """"""
 
@@ -108,6 +119,9 @@ Used to retrieve the last entry/entries made. The number {n} represents the amou
   :ref:`search-para-0.3` :ref:`show-para-0.3`     :ref:`sort-para-0.3`   :ref:`type_id-para-0.3`
 ======================== ======================== ====================== ======================= =============================
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/latest/25
+
 System class
 """"""""""""
 
@@ -125,6 +139,9 @@ Retrieves a list of entities, based on their OpenAtlas system class name as JSON
   :ref:`sort-para-0.3`   :ref:`type_id-para-0.3`
 ======================== ======================= ======================== ============================= ====================== ======================
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/system_class/person
+
 Type entities
 """""""""""""
 
@@ -142,6 +159,9 @@ Used to retrieve a JSON list of entities, based on their OpenAtlas **type** [2]_
   :ref:`sort-para-0.3`   :ref:`type_id-para-0.3`
 ======================== ======================= ======================== ============================= ====================== ======================
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/type_entities/47
+
 Type entities all
 """""""""""""""""
 
@@ -159,6 +179,9 @@ Used to retrieve a JSON list of entities, based on their OpenAtlas **type** and
   :ref:`sort-para-0.3`   :ref:`type_id-para-0.3`
 ======================== ======================= ======================== ============================= ====================== ======================
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/type_entities_all/47
+
 View class
 """"""""""
 
@@ -176,6 +199,9 @@ Used to retrieve a JSON list of entities based on their OpenAtlas class view
   :ref:`sort-para-0.3`   :ref:`type_id-para-0.3`
 ======================== ======================= ======================== ============================= ====================== ======================
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/view_class/actor
+
 
 .. [1] All codes available in OpenAtlas can be found under `OpenAtlas and CIDOC CRM class mapping <https://redmine.openatlas.eu/projects/uni/wiki/OpenAtlas_and_CIDOC_CRM_class_mapping?parent=Endpoints>`_
 .. [2] The result can be filtered, sorted, and manipulated through different parameters. By default 20 entities in alphabetical order are shown.
@@ -202,6 +228,9 @@ Retrieves a list of all types sorted by view class
 :ref:`download-para-0.3`
 ======================== ==
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/type_by_view_class/
+
 Type overview
 """"""""""""""""""
 
@@ -217,6 +246,9 @@ Retrieves a list of all type
 :ref:`download-para-0.3`
 ======================== ==
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/type_overview/
+
 Type tree
 """"""""""""""""""
 
@@ -232,7 +264,8 @@ Shows every *type* in an OpenAtlas instance in hierarchical order.
 :ref:`download-para-0.3`
 ======================== ==
 
-
+**Example**
+    https://demo.openatlas.eu/api/0.3/type_tree/
 
 Administrative endpoints
 ************************
@@ -249,6 +282,9 @@ Classes
 Retrieves a detailed list of all available system classes, their CIDOC CRM mapping, which view they belong to,
 which icon is used, and their english name.
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/classes/
+
 Content
 """"""""""""""""""
 
@@ -265,6 +301,9 @@ intro, legal notice, contact, and size of processed images.
 :ref:`download-para-0.3` :ref:`lang-para-0.3`
 ======================== ====================
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/content/
+
 System class count
 """"""""""""""""""
 
@@ -274,6 +313,8 @@ System class count
 
 Retrieves a list of the numbers of entries connected to a system class
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/system_class_count/
 
 Special endpoints
 *****************
@@ -289,6 +330,9 @@ Export database
 
 Downloads all information in an OpenAtlas instance as CSV, XML, or JSON
 
+**Example**
+    https://demo.openatlas.eu/api/0.3/export_database/json
+
 Geometric entities
 """"""""""""""""""
 
@@ -298,11 +342,14 @@ Geometric entities
 
 Retrieves a detailed GeoJSON list of all chosen geometries in an OpenAtlas instance; this was implemented for map usage
 
-======================== ========================
+======================== ======================== ========================
  **Optional Parameters**
--------------------------------------------------
-:ref:`count-para-0.3`    :ref:`download-para-0.3`
-======================== ========================
+--------------------------------------------------------------------------
+:ref:`count-para-0.3`    :ref:`download-para-0.3` :ref:`geometry-para-0.3`
+======================== ======================== ========================
+
+**Example**
+    https://demo.openatlas.eu/api/0.3/geometric_entities/
 
 Subunits
 """"""""""""""""""
@@ -319,7 +366,6 @@ Displays all subunits of a place in a special format used by the `THANADOS <http
 :ref:`count-para-0.3`    :ref:`download-para-0.3`
 ======================== ========================
 
-
 Image endpoints
 ***************