diff --git a/openatlas/api/endpoints/display_image.py b/openatlas/api/endpoints/display_image.py index 393e63add..84751aeca 100644 --- a/openatlas/api/endpoints/display_image.py +++ b/openatlas/api/endpoints/display_image.py @@ -10,6 +10,7 @@ from openatlas.api.resources.model_mapper import ( get_entities_by_ids, get_entities_by_system_classes, get_entity_by_id) from openatlas.api.resources.parser import files, image +from openatlas.api.resources.resolve_endpoints import download from openatlas.api.resources.templates import licensed_file_template from openatlas.api.resources.util import get_license_name from openatlas.display.util import ( @@ -65,4 +66,6 @@ def get() -> tuple[Any, int]: _external=True), 'license': license_, 'IIIFManifest': iiif_manifest} + if parser['download']: + download(files_dict, licensed_file_template(entities), 'files') return marshal(files_dict, licensed_file_template(entities)), 200 diff --git a/openatlas/api/routes.py b/openatlas/api/routes.py index bda6944c5..524ee8d23 100644 --- a/openatlas/api/routes.py +++ b/openatlas/api/routes.py @@ -63,17 +63,21 @@ def admin_routes(api: Api) -> None: ClassMapping, '/classes/', endpoint='class_mapping') - api.add_resource( - SystemClassCount, - '/system_class_count/', - endpoint='system_class_count') api.add_resource( LicensedFileOverview, '/licensed_file_overview/', endpoint='licensed_file_overview') + api.add_resource( + SystemClassCount, + '/system_class_count/', + endpoint='system_class_count') def type_routes(api: Api) -> None: + api.add_resource( + GetTypeByViewClass, + '/type_by_view_class/', + endpoint="type_by_view_class") api.add_resource( GetTypeOverview, '/type_overview/', @@ -82,10 +86,6 @@ def type_routes(api: Api) -> None: GetTypeTree, '/type_tree/', endpoint="type_tree") - api.add_resource( - GetTypeByViewClass, - '/type_by_view_class/', - endpoint="type_by_view_class") def special_routes(api: Api) -> None: diff --git a/sphinx/source/technical/api.rst b/sphinx/source/technical/api.rst index 7ba16d295..4ab152c7b 100644 --- a/sphinx/source/technical/api.rst +++ b/sphinx/source/technical/api.rst @@ -87,20 +87,22 @@ Versioning ========== .. list-table:: :header-rows: 1 - :widths: 20 20 20 + :widths: 20 20 20 20 * - stable - - unstable - deprecated - * - :ref:`0.3` + - unstable + - unavailable + * - :ref:`0.4` + - :ref:`0.3` + - 1.0 - :ref:`0.1`, :ref:`0.2` - - :ref:`1.0` The OpenAtlas API follows the notion of `sequenced based versioning `_ and reflects the significance: **major.minor.fix** e.g. **3.11.1**. Only the **major** number is used for the URL path. **Minor** and **fix** are used for -documentation reasons only with the exception of versions 0.1, 0.2 and 0.3. +documentation reasons only with the exception of versions 0.1, 0.2, 0.3 and 0.4. A **stable** version of the API will be available at all times. In addition, **previous** versions will still be usable but tagged as **deprecated**. A warning will be posted in the @@ -118,7 +120,8 @@ has a own set of endpoints, be sure to use the right one. .. toctree:: :maxdepth: 1 - Version 0.3 (stable, current) + Version 0.4 (stable, current) + Version 0.3 (stable, deprecated) api_version_02 api_version_01 Version 1.0 (whitepaper) @@ -137,19 +140,17 @@ parameters which can be used. So please consult the `Endpoints`_ listing for more details. Parameters are added to the end of an URL after the "**?**" symbol -(e.g. demo.openatlas.eu/api/0.3/entity/5117**?download=true**) and are +(e.g. demo.openatlas.eu/api/0.4/entity/5117**?download=true**) and are connected with the "**&**" sign. For more general information on this topic see this `article `_. -At the moment only the :ref:`stable version 0.3` of the API can -be provided by an detailed parameter list. - .. toctree:: :maxdepth: 1 api_parameters_03 + api_parameters_04 Error handling ============== diff --git a/sphinx/source/technical/api_parameters_04.rst b/sphinx/source/technical/api_parameters_04.rst new file mode 100644 index 000000000..6f3945737 --- /dev/null +++ b/sphinx/source/technical/api_parameters_04.rst @@ -0,0 +1,521 @@ +API parameters 0.4 +================== + +.. toctree:: + +.. _cidoc-classes-para-0.4: + +.. list-table:: **cidoc_classes** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - string, multiple + * - Description + - CIDOC CRM class code (e.g. E21) + * - Values + - E5, E7, E8, E9, E12, E18, E20, E21, E22, E31, E32, E33, E41, E53, E54, E55, E65, E74 + +.. _column-para-0.4: + +.. list-table:: **column** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - string + * - Description + - Results will be sorted by the given column + * - Values + - | ID + | classCode + | name + | description + | created + | modified + | systemClass + | beginFrom + | beginTo + | endFrom + | endTo + +.. _count-para-0.4: + +.. list-table:: **count** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - boolean + * - Description + - Returns the total count of results as integer + * - Values + - True/False + +.. _download-para-0.4: + +.. list-table:: **download** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - boolean + * - Description + - Triggers file download of the requested data in a file + * - Values + - True/False + +.. _entities-para-0.4: + +.. list-table:: **entities** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - integer, multiple + * - Description + - Specific entity ID + * - Values + - e.g. 89 + +.. _export-para-0.4: + +.. list-table:: **export** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - string + * - Description + - Results will be downloaded in the given format + * - Values + - | csv + | csvNetwork + +.. _file_id-para-0.4: + +.. list-table:: **file_id** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - integer + * - Description + - ID of a file. This parameter can be used multiple times to query more IDs. + * - Values + - e.g. 89 + + +.. _first-para-0.4: + +.. list-table:: **first** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - integer + * - Description + - List of results starting with given ID + * - Values + - e.g. 89 + +.. _format-para-0.4: + +.. list-table:: **format** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - string + * - Description + - Select a preferred output format + * - Values + - | lp + | loud + | geojson + | geojson-v2 + | pretty-xml + | n3 + | turtle + | nt + | xml (subunits endpoint can only handle xml) + +.. _geometry-para-0.4: + +.. list-table:: **geometry** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - string + * - Description + - Select a preferred geometry + * - Values + - | gisAll + | gisPointAll + | gisPointSupers + | gisPointSubs + | gisPointSibling + | gisLineAll + | gisPolygonAll + +.. _id-para-0.4: + +.. list-table:: **id** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - integer + * - Description + - Specific entity ID in OpenAtlas instance + * - Values + - e.g. 89 + +.. _image_size-para-0.4: + +.. list-table:: **image_size** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - string + * - Description + - Select the size category for the displayed image (can be modified in production.py) + * - Values + - | table + | thumbnail + +.. _lang-para-0.4: + +.. list-table:: **lang** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - string + * - Description + - Select an output language + * - Values + - | en + | de + +.. _last-para-0.4: + +.. list-table:: **last** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - integer + * - Description + - JSON list of results start with entity after given ID + * - Values + - e.g. 90 + +.. _latest-para-0.4: + +.. list-table:: **latest** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - integer + * - Description + - | Number of last database entries to be returned. + | Only numbers between 1 and 100 are valid. + * - Values + - 1 - 100 + +.. _limit-para-0.4: + +.. list-table:: **limit** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - integer + * - Description + - Number of entities returned per page + * - Values + - | 0 corresponds to "no limit set" + | Default is set to 20 entities + +.. _none-para-0.4: + +.. list-table:: **none** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - + * - Description + - No parameters are required + * - Values + - + +.. _page-para-0.4: + +.. list-table:: **page** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - integer + * - Description + - Jump to chosen page + * - Values + - e.g. 2 + +.. _relation_type-para-0.4: + +.. list-table:: **relation_type** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - string, multiple + * - Description + - Select which relations are shown + * - Values + - E.g. P53 + +.. _search-para-0.4: + +.. list-table:: **search** + :widths: 10 80 + :stub-columns: 1 + + * - Format + - string, multiple + * - Description + - 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`_ +.. [2] The result can be filtered, sorted, and manipulated through different parameters. By default 20 entities in alphabetical order are shown. +.. [3] Available IDs can be obtained by using the type-tree or node-overview endpoint. + + +Type Endpoints +*************** + +Provide information about Types of an OpenAtlas instance. The results are in JSON and in a custom format. + +Type by View Class +"""""""""""""""""" + +.. code:: + + /api/0.4/type_by_view_class/ + +Retrieves a list of all types sorted by view class + +======================== == + **Optional Parameters** +--------------------------- +:ref:`download-para-0.4` +======================== == + +**Example** + https://demo.openatlas.eu/api/0.4/type_by_view_class/ + +Type Overview +"""""""""""""""""" + +.. code:: + + /api/0.4/type_overview/ + +Retrieves a list of all type + +======================== == + **Optional Parameters** +--------------------------- +:ref:`download-para-0.4` +======================== == + +**Example** + https://demo.openatlas.eu/api/0.4/type_overview/ + +Type Tree +"""""""""""""""""" + +.. code:: + + /api/0.4/type_tree/ + +Shows every *type* in an OpenAtlas instance in hierarchical order. + +======================== == + **Optional Parameters** +--------------------------- +:ref:`download-para-0.4` +======================== == + +**Example** + https://demo.openatlas.eu/api/0.4/type_tree/ + +Administrative Endpoints +************************ + +Provide metadata of the OpenAtlas instance for presentation sites. + +Backend Details +"""""""""""""""""" + +.. code:: + + /api/0.4/backend_details/ + +Retrieves a detailed list of the OpenAtlas version, the available API versions, site name, image and IIIF details. + +**Example** + https://demo.openatlas.eu/api/0.4/backend_details/ + +Classes +"""""""""""""""""" + +.. code:: + + /api/0.4/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.4/classes/ + +Licensed File Overview +"""""""""""""""""" + +.. code:: + + /api/0.4/licensed_file_overview/ + +Retrieves a list of display URL, thumbnail URL, extension and license of all files which exists and have a licence. +With the parameter "file_id", only the given IDs where retrieved. + +**Example** + https://demo.openatlas.eu/api/0.4/licensed_file_overview/ + +======================== ======================= + **Optional Parameters** +------------------------------------------------ +:ref:`download-para-0.4` :ref:`file_id-para-0.4` +======================== ======================= + +System Class Count +"""""""""""""""""" + +.. code:: + + /api/0.4/system_class_count/ + +Retrieves a list of the numbers of entries connected to a system class + +**Example** + https://demo.openatlas.eu/api/0.4/system_class_count/ + +Special Endpoints +***************** + +Provides project-specific formats. + +Export Database +""""""""""""""" + +.. code:: + + /api/0.4/export_database/{format} + +Downloads all information in an OpenAtlas instance as CSV, XML, or JSON + +**Example** + https://demo.openatlas.eu/api/0.4/export_database/json + +Geometric Entities +"""""""""""""""""" + +.. code:: + + /api/0.4/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.4` :ref:`download-para-0.4` :ref:`geometry-para-0.4` +======================== ======================== ======================== + +**Example** + https://demo.openatlas.eu/api/0.4/geometric_entities/ + +Subunits +"""""""" + +.. code:: + + /api/0.4/subunits/{id} + +Displays all subunits of a place in a special format used by the `THANADOS `_ project + +======================== ======================== + **Optional Parameters** +------------------------------------------------- +:ref:`count-para-0.4` :ref:`download-para-0.4` +======================== ======================== + +Image Endpoints +*************** + +Display +""""""" + +.. code:: + + /api/0.4/display/{id} + +Provides the image connected to the requested ID. Be aware, the image will only be displayed if the request comes +from a **logged-in** user or API public setting is set to on and the image has a **license**. + +=========================== ======================== + **Optional Parameters** +---------------------------------------------------- +:ref:`image_size-para-0.4` +=========================== ======================== + diff --git a/tests/test_api.py b/tests/test_api.py index 1fc61fbdf..77fab2cd5 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -435,8 +435,8 @@ def test_api(self) -> None: assert found for rv in [ - self.app.get(url_for('api_03.type_tree')), - self.app.get(url_for('api_03.type_tree', download=True))]: + self.app.get(url_for('api_03.type_tree')), + self.app.get(url_for('api_03.type_tree', download=True))]: assert bool(rv.get_json()['typeTree']) rv = self.app.get(url_for('api_03.type_tree', count=True)) assert rv.get_json() > 0 @@ -790,6 +790,11 @@ def test_api(self) -> None: # Image Endpoints rv = self.app.get(url_for('api_03.licensed_file_overview')) assert bool(len(rv.get_json().keys()) == 3) + rv = self.app.get( + url_for( + 'api_03.licensed_file_overview', + download=True)) + assert bool(len(rv.get_json().keys()) == 3) rv = self.app.get(url_for( 'api_03.licensed_file_overview', file_id='154')) assert bool(len(rv.get_json().keys()) == 1)