From 848aa67a3c8f93cee8a454706020d2f3a76dbf6f Mon Sep 17 00:00:00 2001 From: "G. Allegri" Date: Thu, 2 May 2024 17:20:53 +0200 Subject: [PATCH] improve documentation about upload tracking prograss API --- devel/api/linked_resources/index.rst | 139 --------------------------- devel/api/usage/index.rst | 60 +++++++++--- 2 files changed, 44 insertions(+), 155 deletions(-) delete mode 100644 devel/api/linked_resources/index.rst diff --git a/devel/api/linked_resources/index.rst b/devel/api/linked_resources/index.rst deleted file mode 100644 index 83c014de..00000000 --- a/devel/api/linked_resources/index.rst +++ /dev/null @@ -1,139 +0,0 @@ -=================== -API usage examples -=================== - -| In this section, we are going to demostrate how to use linked resources api - -Linked Resources Listing and Details ------------------------------------- - -All available linked_resources can be listed with API ``GET /api/v2/resources/{pk}/linked_resources``. -where pk Resource base id - -Example Requests: -^^^^^^^^^^^^^^^^^ - -1. List all resource links - -.. code-block:: python - - import requests - - url = "https://master.demo.geonode.org/api/v2/resources/{pk}/linked_resources" - response = requests.request("GET", url) - - - - - - - -To link resources between them the endpoint implements POST and DELETE methods ------------------------------------------------------------------------------- -- /api/v2/resources/{pk}/linked_resources - -Examples: -^^^^^^^^^ -1. Add a resource link - -.. code-block:: python - - import requests - - url = "https://master.demo.geonode.org/api/v2/resources/1797" - payload={'target':[1,2,3]} - response = requests.request("POST", url, data=payload) - - -2. Remove resource link - -.. code-block:: python - - import requests - - url = "https://master.demo.geonode.org/api/v2/resources/1797" - payload={'target':[1,2,3]} - response = requests.request("POST", url, data=payload) - -3. Response POST/DELETE - -.. code-block:: python - - #in the event of a successful post - {"success": [1,2,3],"error": [],"message": "Resources updated successfully"} - #in case the target ids are not updated successfully - {"success": [],"error": [1,2,3],"message": "Something went wrong"} - - - - -GeoNode linked resources can be filtered with the following query parameters: - -.. list-table:: - :widths: 25 100 - :header-rows: 1 - - * - Parameters - - Resource id provided in the url - * - linked resources connected to resource base - - /api/v2/resources/{pk}/linked_resourcest - * - linked resources connected to resource base filtered by resource type - - /api/v2/resources/{pk}/linked_resources?resource_type=map,dataset - * - linked resources connected to resource base filtered by link type - - /api/v2/resources/{pk}/linked_resources?link_type=linked_by - -1. Resource Type can by filtered by multiple values if they're seperated by a comma - -.. code-block:: python - - import requests - - url = "https://master.demo.geonode.org//api/v2/resources/{pk}/linked_resources?resource_type=map,dataset&linked_type=linked_by,linked_to" - response = requests.request("GET", url, headers=headers, data=payload) - -2. Filter with linked_type - -.. code-block:: python - - import requests - - url = "https://master.demo.geonode.org//api/v2/resources/{pk}/linked_resources?link_type=linked_to" - - response = requests.request("GET", url, headers=headers) - -===================== -Response GET -===================== - -The api will respond with with the follwing payload based on present filters - --------------------------------------------------------------------------------- - - -.. code-block:: python - - { - "WARNINGS": { - "DEPRECATION": "'resources' field is deprecated, please use 'linked_to'" - }, - "resources": [{ - "pk": 3, - "title": ">>> vertexes", - "resource_type": "dataset", - "detail_url": "/catalogue/#/dataset/3", - "thumbnail_url": "http://localhost:8000/upload1.jpg" - }], - "linked_to": [ - { - "internal": false, - "pk": 3, - "title": "vertexes", - "resource_type": "dataset", - "detail_url": "/catalogue/#/dataset/3", - "thumbnail_url": "http://localhost:8000/uploaded/thumbs/dataset-ac0cd7d6931.jpg" - }], - "linked_by": [] - } - - - diff --git a/devel/api/usage/index.rst b/devel/api/usage/index.rst index f4b98e36..920bb26f 100644 --- a/devel/api/usage/index.rst +++ b/devel/api/usage/index.rst @@ -281,21 +281,31 @@ Example: Tracking dataset upload progress ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When an upload request is executed, GeoNode creates an “upload object” and keeps updating its state and progress (it’s a property attribute, calculated on getting the response) attributes as the resource is being created and configured in Geoserver. -The states used include: - - READY - - RUNNING - - PENDING - - WAITING - - INCOMPLETE - - COMPLETE - - INVALID - - PROCESSED - -When the dataset is successfully uploaded, the final state of the upload is set to ``PROCESSED`` and progress is calculated as ``100.0``. - -In order to view ongoing uploads, and their states, you can use the API ``GET /api/v2/uploads`` or ``GET /api/v2/uploads/{id}`` if the upload id is known. You can also filter uploads with state. -Eg ``GET /api/v2/uploads?filter{state}=PROCESSED`` +When an upload request is executed, GeoNode creates an "Execution request" and keeps updating its state and progress (it’s a property attribute, calculated on getting the response) attributes as the resource is being created and configured in Geoserver. +An execution can be in one of the following status: + - ``ready`` + - ``running`` + - ``failed`` + - ``finished`` + +When the dataset is successfully uploaded, the final state of the upload is set to ``finished``. + +In order to view status of the execution, the API method ``GET /api/v2/executionrequest/{execution_id}`` where ``{execution_id}`` is the value returned by the initial call to the upload API. + +The returned object contains, beyond all the information related to the execution, the inputs that were passed to the execution request, and output params specific to the type of execution. +In the case of a dataset upload, the output params contain the URL of the catalog page for the new datast. + +.. code-block:: json + + "output_params": { + "detail_url": [ + "/catalogue/#/dataset/9881" + ] + }, + +You can also filter executions by status. +Eg ``GET /api/v2/executionrequest?filter{action}=import&filter{source}=upload&filter{status}=finished`` + Example: @@ -303,7 +313,7 @@ Example: import requests - url = "https://master.demo.geonode.org/api/v2/uploads" + url = "https://stable.demo.geonode.org/api/v2/executionrequest/5f640b6b-8c51-4514-a054-995133fee107" headers = { 'Authorization': 'Basic dXNlcjpwYXNzd29yZA==' } @@ -630,3 +640,21 @@ The ``status_url`` property returns the URL to track kthe progress of the reques The operation will be completed once the ``status`` property is updated with the value ``finished``. + +Linked Resources Listing and Details +------------------------------------ + +All available linked_resources can be listed with API ``GET /api/v2/resources/{pk}/linked_resources``. +where pk Resource base id + +Example Requests: +^^^^^^^^^^^^^^^^^ + +1. List all resource links + +.. code-block:: python + + import requests + + url = "https://master.demo.geonode.org/api/v2/resources/{pk}/linked_resources" + response = requests.request("GET", url)