From ba8ab4ccc5704bd96092b1525fa3dd1e3352a0b0 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Wed, 18 Dec 2024 21:18:29 +0100 Subject: [PATCH 01/31] Enhance scenario bundle feature documentation: - Move information from web api section as it explains how the scenario bundle json object is handled by django ans describes the interfaces --- .../features/scenario-bundles/index.md | 584 +++++++++++++++++- 1 file changed, 582 insertions(+), 2 deletions(-) diff --git a/docs/oeplatform-code/features/scenario-bundles/index.md b/docs/oeplatform-code/features/scenario-bundles/index.md index c8af800f9..f6b9edfa4 100644 --- a/docs/oeplatform-code/features/scenario-bundles/index.md +++ b/docs/oeplatform-code/features/scenario-bundles/index.md @@ -21,8 +21,6 @@ Database - A graph database is used to store the complex data structure of the scenario bundles in the long term. We use Appache Jenna-Fuseki as a reliable technology. -## Functionalities - ## Code Documentation ### Django view for the scenario bundles @@ -65,3 +63,585 @@ Some of the information on this page may be changed in the future. To review the `def get_entities_by_type(request, *args, **kwargs):` #### ::: factsheet.views.get_entities_by_type + +### The scenario bundle object construction and API in django + +Below we describe how we construct the Scenario bundles in the scenario bundles django app. Using JSON as an input format the complex scenario bundle object becomes more manageable when working with WEB-technologies. Users will create a scenario bundle using a user interface with input text and selection fields this information is send and processed as JSON before it is stored in the OEKG using RDF´s triple notation. + +You can read the following sections as: This is how django processes the data, and this is where the data is send once the user submits or changes a scenario bundles. The URL pointing out what django view will handle the JSON object below. This is very similar to what general web api´s do like REST-API´s. The exception here is that there is an CSRF Token involved which is required by the django backend to make sure requests are save and do not originate form an unsafe source allowing the scenario bundle frontend to send data to the backend. + +The technology that drives this implementation is HTTP. The JSON objects and key:value information is send in packaged as a payload that is send along with each requests. A requests can be triggered by multiple actions for example a button that is pressed by the user. Based on the URL and the payload the backend can determine what functionality must be triggered. This can be for example creating a scenario bundle or retrieving a specific bundle by its ID. + +!!! note + Some of the information on this page may be changed in the future. To review the most recent information, please revisit. + +#### Create a new bundle in OEKG + +`https://openenergy-platform.org/scenario-bundles/add/` + +An example of input parameters + +```json +{ + "id": "new", + "uid": "6157d6d6-7a7b-a61e-21d3-a8f936b19056", + "study_name": "Example study name", + "acronym": "Example acronym", + "abstract": "Example abstract ...", + "institution": [ + { + "iri": "708ad5dc-7f8b-6c65-6a5f-0fc54fe8221b", + "name": "Öko-Institut e.V." + }, + { + "iri": "8e1515b9-9b1f-fa06-a3a2-d552b0ea7dcd", + "name": "Otto-von-Guericke-Universität Magdeburg" + } + ], + "funding_source": [ + { + "iri": "82dd628d-f748-560b-b0cd-06466cf90f1a", + "name": "Bundesministerium für Umwelt, Naturschutz und nukleare Sicherheit" + } + ], + "contact_person": [], + "sector_divisions": [], + "sectors": [ + { + "label": "KSG sector buildings", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010067" + }, + { + "label": "KSG sector industry", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010066" + }, + { + "label": "CRF sector (IPCC 2006): wetlands", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010192" + }, + { + "label": "CRF sector (IPCC 2006): other product manufacture and use", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010172" + }, + { + "label": "CRF sector (IPCC 2006): manure management", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010180" + }, + { + "label": "CRF sector (IPCC 2006): multilateral operations", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010203" + }, + { + "label": "CRF sector (IPCC 2006): chemical industry - other", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010353" + } + ], + "technologies": [ + { + "label": "power generation technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010423" + }, + { + "label": "wind power technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010424" + }, + { + "label": "offshore wind power technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010426" + }, + { + "label": "solar thermal power technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010429" + }, + { + "label": "hydro power technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010431" + }, + { + "label": "run of river power technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010432" + } + ], + "study_descriptors": [ + "life cycle analysis", + "(changes in) demand", + "degree of electrifiaction", + "Reallabor", + "regionalisation", + "peak electricity generation" + ], + "report_title": "Example report title", + "date_of_publication": " 2021", + "report_doi": "5345-43-5634-6-346-46-43", + "place_of_publication": "", + "link_to_study": " https://openenergy-platform.org/", + "authors": [], + "scenarios": [ + { + "id": "4974db65-542d-31cd-6f08-11ef9a58680a", + "name": "Example scenario name 1 ", + "acronym": "Example scenario acronym 1 ", + "abstract": "Example scenario abstract 1 ... ", + "regions": [ + { + "name ": "Germany ", + "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Germany " + } + ], + "interacting_regions": [ + { + "name ": "Spain ", + "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Spain " + } + ], + "scenario_years": [ + { + "iri ": "33131404-e58e-12bc-170e-32aba1c83d99 ", + "name ": "2021 " + } + ], + "descriptors ": [ + { + "label": "explorative scenario ", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00020248 " + }, + { + "label": "policy scenario ", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00020309 " + }, + { + "label": "climate scenario ", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00030007" + } + ], + "input_datasets": [ + { + "key": "f2d32e9c-1fa0-4d66-9ffd-c297d4bb5c9a ", + "idx": 0, + "value ": { + "label ": "abbb_transmission_capacity ", + "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transmission_capacity " + } + }, + { + "key ": "ca9c82f3-9ba0-7d71-6601-dd520680bedb ", + "idx ": 1, + "value ": { + "label ": "abbb_demand ", + "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_demand " + } + } + ], + "output_datasets ": [ + { + "key ": "0db015dd-1543-f0e9-9579-3602fb16a680 ", + "idx ": 0, + "value ": { + "label ": "abbb_transformer ", + "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transformer " + } + } + ] + }, + { + "id ": "1f4bb594-4b1c-dca4-2465-e04a54eec10b ", + "name ": "Example scenario name 2 ", + "acronym ": "Example scenario acronym 2 ", + "abstract ": "Example scenario abstract 2 ... ", + "regions ": [ + { + "name ": "France ", + "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/France " + } + ], + "interacting_regions ": [ + { + "name ": "Germany ", + "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Germany " + } + ], + "scenario_years ": [], + "descriptors ": [ + { + "label ": "explorative scenario ", + "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020248 " + }, + { + "label ": "with additional measures scenario ", + "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020312 " + }, + { + "label ": "greenhouse gas emission scenario ", + "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020317 " + }, + { + "label ": "climate scenario ", + "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00030007 " + }, + { + "label ": "economic scenario ", + "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00030008 " + } + ], + "input_datasets ": [ + { + "key ": "bfc811ee-11f5-6a5a-247d-6f66bb676dd9 ", + "idx ": 0, + "value ": { + "label ": "abbb_transformer ", + "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transformer " + } + } + ], + "output_datasets ": [ + { + "key ": "fbc30f51-7f32-9c21-dfb2-7534aeac538d ", + "idx ": 0, + "value ": { + "label ": "ego_slp_parameters ", + "iri ": "https://openenergy-platform.org/dataedit/view/scenario/ego_slp_parameters " + } + } + ] + } + ], + "models": [ + { + "id ": "SciGrid: Open Source Reference Model of European Transmission Networks for Scientific Analysis ", + "name ": "SciGrid: Open Source Reference Model of European Transmission Networks for Scientific Analysis " + }, + { + "id ": "Balmorel ", + "name ": "Balmorel " + }, + { + "id ": "National Electricity Market Optimiser ", + "name ": "National Electricity Market Optimiser " + }, + { + "id ": "urbs Bavaria ", + "name ": "urbs Bavaria " + } + ], + "frameworks": [ + { + "id ": "Python for Power System Analysis toolbox (PyPSA) ", + "name ": "Python for Power System Analysis toolbox (PyPSA) " + }, + { + "id ": "Framework for Integrated Energy System Assessment ", + "name ": "Framework for Integrated Energy System Assessment " + }, + { + "id ": "Model Order Reduction for Gas and Energy Networks ", + "name ": "Model Order Reduction for Gas and Energy Networks " + }, + { + "id ": "OMEGAlpes ", + "name ": "OMEGAlpes " + }, + { + "id ": "Potsdam Integrated Assessment Modeling Framework (PIAM) ", + "name ": "Potsdam Integrated Assessment Modeling Framework (PIAM) " + } + ] +} +``` + +#### Get a bundle in OEKG + +Retrieve a bundle by its `uid` + +`https://openenergy-platform.org/scenario-bundles/get/` + +An example of input parameters + +```json +"uid" : "6157d6d6-7a7b-a61e-21d3-a8f936b19056", +``` + +#### Remove a bundle from OEKG + +`https://openenergy-platform.org/scenario-bundles/delete/` + +To delete a bundle, the `uid` of the bundle should be provided. + +An example of input parameters + +```json +"uid" : "6157d6d6-7a7b-a61e-21d3-a8f936b19056", +``` + +#### Update a bundle in OEKG + +`https://openenergy-platform.org/scenario-bundles/update/` + +An example of input parameters + +The `uid` should belong to an existing bundle in OEKG. The remaining fields are identical to those in the create bundle API. + +```json +{ + "uid": "6157d6d6-7a7b-a61e-21d3-a8f936b19056", + "study_name": "Example study name", + "acronym": "Example acronym", + "abstract": "Example abstract ...", + "institution": [ + { + "iri": "708ad5dc-7f8b-6c65-6a5f-0fc54fe8221b", + "name": "Öko-Institut e.V." + }, + { + "iri": "8e1515b9-9b1f-fa06-a3a2-d552b0ea7dcd", + "name": "Otto-von-Guericke-Universität Magdeburg" + } + ], + "funding_source": [ + { + "iri": "82dd628d-f748-560b-b0cd-06466cf90f1a", + "name": "Bundesministerium für Umwelt, Naturschutz und nukleare Sicherheit" + } + ], + "contact_person": [], + "sector_divisions": [], + "sectors": [ + { + "label": "KSG sector buildings", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010067" + }, + { + "label": "KSG sector industry", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010066" + }, + { + "label": "CRF sector (IPCC 2006): wetlands", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010192" + }, + { + "label": "CRF sector (IPCC 2006): other product manufacture and use", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010172" + }, + { + "label": "CRF sector (IPCC 2006): manure management", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010180" + }, + { + "label": "CRF sector (IPCC 2006): multilateral operations", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010203" + }, + { + "label": "CRF sector (IPCC 2006): chemical industry - other", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010353" + } + ], + "technologies": [ + { + "label": "power generation technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010423" + }, + { + "label": "wind power technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010424" + }, + { + "label": "offshore wind power technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010426" + }, + { + "label": "solar thermal power technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010429" + }, + { + "label": "hydro power technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010431" + }, + { + "label": "run of river power technology", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010432" + } + ], + "study_descriptors": [ + "life cycle analysis", + "(changes in) demand", + "degree of electrifiaction", + "Reallabor", + "regionalisation", + "peak electricity generation" + ], + "report_title": "Example report title", + "date_of_publication": " 2021", + "report_doi": "5345-43-5634-6-346-46-43", + "place_of_publication": "", + "link_to_study": " https://openenergy-platform.org/", + "authors": [], + "scenarios": [ + { + "id": "4974db65-542d-31cd-6f08-11ef9a58680a", + "name": "Example scenario name 1 ", + "acronym": "Example scenario acronym 1 ", + "abstract": "Example scenario abstract 1 ... ", + "regions": [ + { + "name ": "Germany ", + "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Germany " + } + ], + "interacting_regions": [ + { + "name ": "Spain ", + "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Spain " + } + ], + "scenario_years": [ + { + "iri ": "33131404-e58e-12bc-170e-32aba1c83d99 ", + "name ": "2021 " + } + ], + "descriptors ": [ + { + "label": "explorative scenario ", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00020248 " + }, + { + "label": "policy scenario ", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00020309 " + }, + { + "label": "climate scenario ", + "class": "http://openenergy-platform.org/ontology/oeo/OEO_00030007" + } + ], + "input_datasets": [ + { + "key": "f2d32e9c-1fa0-4d66-9ffd-c297d4bb5c9a ", + "idx": 0, + "value ": { + "label ": "abbb_transmission_capacity ", + "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transmission_capacity " + } + }, + { + "key ": "ca9c82f3-9ba0-7d71-6601-dd520680bedb ", + "idx ": 1, + "value ": { + "label ": "abbb_demand ", + "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_demand " + } + } + ], + "output_datasets ": [ + { + "key ": "0db015dd-1543-f0e9-9579-3602fb16a680 ", + "idx ": 0, + "value ": { + "label ": "abbb_transformer ", + "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transformer " + } + } + ] + }, + { + "id ": "1f4bb594-4b1c-dca4-2465-e04a54eec10b ", + "name ": "Example scenario name 2 ", + "acronym ": "Example scenario acronym 2 ", + "abstract ": "Example scenario abstract 2 ... ", + "regions ": [ + { + "name ": "France ", + "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/France " + } + ], + "interacting_regions ": [ + { + "name ": "Germany ", + "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Germany " + } + ], + "scenario_years ": [], + "descriptors ": [ + { + "label ": "explorative scenario ", + "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020248 " + }, + { + "label ": "with additional measures scenario ", + "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020312 " + }, + { + "label ": "greenhouse gas emission scenario ", + "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020317 " + }, + { + "label ": "climate scenario ", + "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00030007 " + }, + { + "label ": "economic scenario ", + "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00030008 " + } + ], + "input_datasets ": [ + { + "key ": "bfc811ee-11f5-6a5a-247d-6f66bb676dd9 ", + "idx ": 0, + "value ": { + "label ": "abbb_transformer ", + "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transformer " + } + } + ], + "output_datasets ": [ + { + "key ": "fbc30f51-7f32-9c21-dfb2-7534aeac538d ", + "idx ": 0, + "value ": { + "label ": "ego_slp_parameters ", + "iri ": "https://openenergy-platform.org/dataedit/view/scenario/ego_slp_parameters " + } + } + ] + } + ], + "models": [ + { + "id ": "SciGrid: Open Source Reference Model of European Transmission Networks for Scientific Analysis ", + "name ": "SciGrid: Open Source Reference Model of European Transmission Networks for Scientific Analysis " + }, + { + "id ": "Balmorel ", + "name ": "Balmorel " + }, + { + "id ": "National Electricity Market Optimiser ", + "name ": "National Electricity Market Optimiser " + }, + { + "id ": "urbs Bavaria ", + "name ": "urbs Bavaria " + } + ], + "frameworks": [ + { + "id ": "Python for Power System Analysis toolbox (PyPSA) ", + "name ": "Python for Power System Analysis toolbox (PyPSA) " + }, + { + "id ": "Framework for Integrated Energy System Assessment ", + "name ": "Framework for Integrated Energy System Assessment " + }, + { + "id ": "Model Order Reduction for Gas and Energy Networks ", + "name ": "Model Order Reduction for Gas and Energy Networks " + }, + { + "id ": "OMEGAlpes ", + "name ": "OMEGAlpes " + }, + { + "id ": "Potsdam Integrated Assessment Modeling Framework (PIAM) ", + "name ": "Potsdam Integrated Assessment Modeling Framework (PIAM) " + } + ] +} +``` From 777191496f9dec07c6d0305b604f223153eae34c Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Wed, 18 Dec 2024 21:19:50 +0100 Subject: [PATCH 02/31] Enhance and extend the oekg web api documentation usage example & provide a openapo schema as api endpoint documentation --- .../oeplatform-code/web-api/oekg-api/index.md | 625 ++---------------- 1 file changed, 45 insertions(+), 580 deletions(-) diff --git a/docs/oeplatform-code/web-api/oekg-api/index.md b/docs/oeplatform-code/web-api/oekg-api/index.md index d0fa9a347..a8e82e053 100644 --- a/docs/oeplatform-code/web-api/oekg-api/index.md +++ b/docs/oeplatform-code/web-api/oekg-api/index.md @@ -1,596 +1,61 @@ -### Django view for the scenario bundles +## OEKG web based access -!!! note -Some of the information on this page may be changed in the future. To review the most recent information, please revisit. - -### Create a new bundle in OEKG - -`https://openenergy-platform.org/scenario-bundles/add/` - -An example of input parameters - -```json -{ - "id": "new", - "uid": "6157d6d6-7a7b-a61e-21d3-a8f936b19056", - "study_name": "Example study name", - "acronym": "Example acronym", - "abstract": "Example abstract ...", - "institution": [ - { - "iri": "708ad5dc-7f8b-6c65-6a5f-0fc54fe8221b", - "name": "Öko-Institut e.V." - }, - { - "iri": "8e1515b9-9b1f-fa06-a3a2-d552b0ea7dcd", - "name": "Otto-von-Guericke-Universität Magdeburg" - } - ], - "funding_source": [ - { - "iri": "82dd628d-f748-560b-b0cd-06466cf90f1a", - "name": "Bundesministerium für Umwelt, Naturschutz und nukleare Sicherheit" - } - ], - "contact_person": [], - "sector_divisions": [], - "sectors": [ - { - "label": "KSG sector buildings", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010067" - }, - { - "label": "KSG sector industry", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010066" - }, - { - "label": "CRF sector (IPCC 2006): wetlands", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010192" - }, - { - "label": "CRF sector (IPCC 2006): other product manufacture and use", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010172" - }, - { - "label": "CRF sector (IPCC 2006): manure management", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010180" - }, - { - "label": "CRF sector (IPCC 2006): multilateral operations", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010203" - }, - { - "label": "CRF sector (IPCC 2006): chemical industry - other", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010353" - } - ], - "technologies": [ - { - "label": "power generation technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010423" - }, - { - "label": "wind power technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010424" - }, - { - "label": "offshore wind power technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010426" - }, - { - "label": "solar thermal power technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010429" - }, - { - "label": "hydro power technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010431" - }, - { - "label": "run of river power technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010432" - } - ], - "study_descriptors": [ - "life cycle analysis", - "(changes in) demand", - "degree of electrifiaction", - "Reallabor", - "regionalisation", - "peak electricity generation" - ], - "report_title": "Example report title", - "date_of_publication": " 2021", - "report_doi": "5345-43-5634-6-346-46-43", - "place_of_publication": "", - "link_to_study": " https://openenergy-platform.org/", - "authors": [], - "scenarios": [ - { - "id": "4974db65-542d-31cd-6f08-11ef9a58680a", - "name": "Example scenario name 1 ", - "acronym": "Example scenario acronym 1 ", - "abstract": "Example scenario abstract 1 ... ", - "regions": [ - { - "name ": "Germany ", - "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Germany " - } - ], - "interacting_regions": [ - { - "name ": "Spain ", - "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Spain " - } - ], - "scenario_years": [ - { - "iri ": "33131404-e58e-12bc-170e-32aba1c83d99 ", - "name ": "2021 " - } - ], - "descriptors ": [ - { - "label": "explorative scenario ", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00020248 " - }, - { - "label": "policy scenario ", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00020309 " - }, - { - "label": "climate scenario ", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00030007" - } - ], - "input_datasets": [ - { - "key": "f2d32e9c-1fa0-4d66-9ffd-c297d4bb5c9a ", - "idx": 0, - "value ": { - "label ": "abbb_transmission_capacity ", - "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transmission_capacity " - } - }, - { - "key ": "ca9c82f3-9ba0-7d71-6601-dd520680bedb ", - "idx ": 1, - "value ": { - "label ": "abbb_demand ", - "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_demand " - } - } - ], - "output_datasets ": [ - { - "key ": "0db015dd-1543-f0e9-9579-3602fb16a680 ", - "idx ": 0, - "value ": { - "label ": "abbb_transformer ", - "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transformer " - } - } - ] - }, - { - "id ": "1f4bb594-4b1c-dca4-2465-e04a54eec10b ", - "name ": "Example scenario name 2 ", - "acronym ": "Example scenario acronym 2 ", - "abstract ": "Example scenario abstract 2 ... ", - "regions ": [ - { - "name ": "France ", - "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/France " - } - ], - "interacting_regions ": [ - { - "name ": "Germany ", - "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Germany " - } - ], - "scenario_years ": [], - "descriptors ": [ - { - "label ": "explorative scenario ", - "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020248 " - }, - { - "label ": "with additional measures scenario ", - "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020312 " - }, - { - "label ": "greenhouse gas emission scenario ", - "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020317 " - }, - { - "label ": "climate scenario ", - "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00030007 " - }, - { - "label ": "economic scenario ", - "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00030008 " - } - ], - "input_datasets ": [ - { - "key ": "bfc811ee-11f5-6a5a-247d-6f66bb676dd9 ", - "idx ": 0, - "value ": { - "label ": "abbb_transformer ", - "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transformer " - } - } - ], - "output_datasets ": [ - { - "key ": "fbc30f51-7f32-9c21-dfb2-7534aeac538d ", - "idx ": 0, - "value ": { - "label ": "ego_slp_parameters ", - "iri ": "https://openenergy-platform.org/dataedit/view/scenario/ego_slp_parameters " - } - } - ] - } - ], - "models": [ - { - "id ": "SciGrid: Open Source Reference Model of European Transmission Networks for Scientific Analysis ", - "name ": "SciGrid: Open Source Reference Model of European Transmission Networks for Scientific Analysis " - }, - { - "id ": "Balmorel ", - "name ": "Balmorel " - }, - { - "id ": "National Electricity Market Optimiser ", - "name ": "National Electricity Market Optimiser " - }, - { - "id ": "urbs Bavaria ", - "name ": "urbs Bavaria " - } - ], - "frameworks": [ - { - "id ": "Python for Power System Analysis toolbox (PyPSA) ", - "name ": "Python for Power System Analysis toolbox (PyPSA) " - }, - { - "id ": "Framework for Integrated Energy System Assessment ", - "name ": "Framework for Integrated Energy System Assessment " - }, - { - "id ": "Model Order Reduction for Gas and Energy Networks ", - "name ": "Model Order Reduction for Gas and Energy Networks " - }, - { - "id ": "OMEGAlpes ", - "name ": "OMEGAlpes " - }, - { - "id ": "Potsdam Integrated Assessment Modeling Framework (PIAM) ", - "name ": "Potsdam Integrated Assessment Modeling Framework (PIAM) " - } - ] -} -``` - -### Get a bundle in OEKG - -Retrieve a bundle by its `uid` - -`https://openenergy-platform.org/scenario-bundles/get/` - -An example of input parameters - -```json -"uid" : "6157d6d6-7a7b-a61e-21d3-a8f936b19056", -``` - -### Remove a bundle from OEKG - -`https://openenergy-platform.org/scenario-bundles/delete/` - -To delete a bundle, the `uid` of the bundle should be provided. - -An example of input parameters - -```json -"uid" : "6157d6d6-7a7b-a61e-21d3-a8f936b19056", -``` - -### Update a bundle in OEKG - -`https://openenergy-platform.org/scenario-bundles/update/` - -An example of input parameters - -The `uid` should belong to an existing bundle in OEKG. The remaining fields are identical to those in the create bundle API. - -```json -{ - "uid": "6157d6d6-7a7b-a61e-21d3-a8f936b19056", - "study_name": "Example study name", - "acronym": "Example acronym", - "abstract": "Example abstract ...", - "institution": [ - { - "iri": "708ad5dc-7f8b-6c65-6a5f-0fc54fe8221b", - "name": "Öko-Institut e.V." - }, - { - "iri": "8e1515b9-9b1f-fa06-a3a2-d552b0ea7dcd", - "name": "Otto-von-Guericke-Universität Magdeburg" - } - ], - "funding_source": [ - { - "iri": "82dd628d-f748-560b-b0cd-06466cf90f1a", - "name": "Bundesministerium für Umwelt, Naturschutz und nukleare Sicherheit" - } - ], - "contact_person": [], - "sector_divisions": [], - "sectors": [ - { - "label": "KSG sector buildings", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010067" - }, - { - "label": "KSG sector industry", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010066" - }, - { - "label": "CRF sector (IPCC 2006): wetlands", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010192" - }, - { - "label": "CRF sector (IPCC 2006): other product manufacture and use", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010172" - }, - { - "label": "CRF sector (IPCC 2006): manure management", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010180" - }, - { - "label": "CRF sector (IPCC 2006): multilateral operations", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010203" - }, - { - "label": "CRF sector (IPCC 2006): chemical industry - other", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010353" - } - ], - "technologies": [ - { - "label": "power generation technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010423" - }, - { - "label": "wind power technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010424" - }, - { - "label": "offshore wind power technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010426" - }, - { - "label": "solar thermal power technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010429" - }, - { - "label": "hydro power technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010431" - }, - { - "label": "run of river power technology", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00010432" - } - ], - "study_descriptors": [ - "life cycle analysis", - "(changes in) demand", - "degree of electrifiaction", - "Reallabor", - "regionalisation", - "peak electricity generation" - ], - "report_title": "Example report title", - "date_of_publication": " 2021", - "report_doi": "5345-43-5634-6-346-46-43", - "place_of_publication": "", - "link_to_study": " https://openenergy-platform.org/", - "authors": [], - "scenarios": [ - { - "id": "4974db65-542d-31cd-6f08-11ef9a58680a", - "name": "Example scenario name 1 ", - "acronym": "Example scenario acronym 1 ", - "abstract": "Example scenario abstract 1 ... ", - "regions": [ - { - "name ": "Germany ", - "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Germany " - } - ], - "interacting_regions": [ - { - "name ": "Spain ", - "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Spain " - } - ], - "scenario_years": [ - { - "iri ": "33131404-e58e-12bc-170e-32aba1c83d99 ", - "name ": "2021 " - } - ], - "descriptors ": [ - { - "label": "explorative scenario ", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00020248 " - }, - { - "label": "policy scenario ", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00020309 " - }, - { - "label": "climate scenario ", - "class": "http://openenergy-platform.org/ontology/oeo/OEO_00030007" - } - ], - "input_datasets": [ - { - "key": "f2d32e9c-1fa0-4d66-9ffd-c297d4bb5c9a ", - "idx": 0, - "value ": { - "label ": "abbb_transmission_capacity ", - "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transmission_capacity " - } - }, - { - "key ": "ca9c82f3-9ba0-7d71-6601-dd520680bedb ", - "idx ": 1, - "value ": { - "label ": "abbb_demand ", - "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_demand " - } - } - ], - "output_datasets ": [ - { - "key ": "0db015dd-1543-f0e9-9579-3602fb16a680 ", - "idx ": 0, - "value ": { - "label ": "abbb_transformer ", - "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transformer " - } - } - ] - }, - { - "id ": "1f4bb594-4b1c-dca4-2465-e04a54eec10b ", - "name ": "Example scenario name 2 ", - "acronym ": "Example scenario acronym 2 ", - "abstract ": "Example scenario abstract 2 ... ", - "regions ": [ - { - "name ": "France ", - "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/France " - } - ], - "interacting_regions ": [ - { - "name ": "Germany ", - "iri ": "https://www.omg.org/spec/LCC/Countries/ISO3166-1-CountryCodes/Germany " - } - ], - "scenario_years ": [], - "descriptors ": [ - { - "label ": "explorative scenario ", - "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020248 " - }, - { - "label ": "with additional measures scenario ", - "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020312 " - }, - { - "label ": "greenhouse gas emission scenario ", - "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00020317 " - }, - { - "label ": "climate scenario ", - "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00030007 " - }, - { - "label ": "economic scenario ", - "class ": "http://openenergy-platform.org/ontology/oeo/OEO_00030008 " - } - ], - "input_datasets ": [ - { - "key ": "bfc811ee-11f5-6a5a-247d-6f66bb676dd9 ", - "idx ": 0, - "value ": { - "label ": "abbb_transformer ", - "iri ": "https://openenergy-platform.org/dataedit/view/scenario/abbb_transformer " - } - } - ], - "output_datasets ": [ - { - "key ": "fbc30f51-7f32-9c21-dfb2-7534aeac538d ", - "idx ": 0, - "value ": { - "label ": "ego_slp_parameters ", - "iri ": "https://openenergy-platform.org/dataedit/view/scenario/ego_slp_parameters " - } - } - ] - } - ], - "models": [ - { - "id ": "SciGrid: Open Source Reference Model of European Transmission Networks for Scientific Analysis ", - "name ": "SciGrid: Open Source Reference Model of European Transmission Networks for Scientific Analysis " - }, - { - "id ": "Balmorel ", - "name ": "Balmorel " - }, - { - "id ": "National Electricity Market Optimiser ", - "name ": "National Electricity Market Optimiser " - }, - { - "id ": "urbs Bavaria ", - "name ": "urbs Bavaria " - } - ], - "frameworks": [ - { - "id ": "Python for Power System Analysis toolbox (PyPSA) ", - "name ": "Python for Power System Analysis toolbox (PyPSA) " - }, - { - "id ": "Framework for Integrated Energy System Assessment ", - "name ": "Framework for Integrated Energy System Assessment " - }, - { - "id ": "Model Order Reduction for Gas and Energy Networks ", - "name ": "Model Order Reduction for Gas and Energy Networks " - }, - { - "id ": "OMEGAlpes ", - "name ": "OMEGAlpes " - }, - { - "id ": "Potsdam Integrated Assessment Modeling Framework (PIAM) ", - "name ": "Potsdam Integrated Assessment Modeling Framework (PIAM) " - } - ] -} -``` +In this document we describe how you can access the contents of the OEKG via Web based Requests using HTTP ### The SPARQL endpoint for OEKG `https://openenergyplatform.org/oekg/sparql/` -Here is an example of how to query the Open Energy Knowledge Graph (OEKG) using SPARQL. +Here is an example of how to query the Open Energy Knowledge Graph (OEKG) using SPARQL using python and the requests library for http requests. ```python import requests sparql_endpoint = "https://openenergy-platform.org/oekg/sparql/" -sparql_query = { +payload = { "query": """SELECT ?s ?p ?o - WHERE { - ?s ?p ?o - }""" + WHERE { + ?s ?p ?o + }""" + "format": "json-ld" } -r = requests.get(url=sparql_endpoint, params=sparql_query) +r = requests.post(url=sparql_endpoint, json=payload) print(r.json()) ``` + +## Open API + +Below you see a draft version of the OpenAPI-based. It is the documentation for all HTTP-API endpoints and in the future it can be used to test out the API. + + + + + + API Documentation + + + + + +
+ + + From 9b4be451603c83ad922bcd25a5a07b34d951d42f Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Wed, 18 Dec 2024 21:20:47 +0100 Subject: [PATCH 03/31] add new path that provides info what return formats are available for the sparql query --- oekg/urls.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/oekg/urls.py b/oekg/urls.py index 46027d9ba..ac56a59a5 100644 --- a/oekg/urls.py +++ b/oekg/urls.py @@ -1,8 +1,9 @@ from django.urls import path -from .views import main_view, sparql_endpoint +from .views import main_view, sparql_endpoint, sparql_metadata urlpatterns = [ path("gui/", main_view, name="main"), path("sparql/", sparql_endpoint, name="sparql_endpoint"), + path("sparql_info/", sparql_metadata, name="sparql_endpoint_info"), ] From 1b8eea380c7c9c6b2be5cad567e6396a17ab66be Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Wed, 18 Dec 2024 21:21:55 +0100 Subject: [PATCH 04/31] enhance the sparql query endpoint by implementing return formats and implement new metadata view to provide useful information on available formats --- oekg/views.py | 48 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/oekg/views.py b/oekg/views.py index 8291ea4a9..0f4178dd6 100644 --- a/oekg/views.py +++ b/oekg/views.py @@ -1,11 +1,11 @@ import requests from django.core.exceptions import SuspiciousOperation -from django.http import HttpResponseBadRequest, JsonResponse +from django.http import HttpResponse, HttpResponseBadRequest, JsonResponse from django.shortcuts import render -from django.views.decorators.http import require_POST +from django.views.decorators.http import require_GET, require_POST -from oeplatform.settings import OEKG_SPARQL_ENDPOINT_URL from oekg.utils import validate_sparql_query +from oeplatform.settings import OEKG_SPARQL_ENDPOINT_URL def main_view(request): @@ -17,6 +17,17 @@ def main_view(request): @require_POST def sparql_endpoint(request): sparql_query = request.POST.get("query", "") + response_format = request.POST.get( + "format", "application/sparql-results+json" + ) # Default format + + # Whitelist of supported formats + supported_formats = { + "json": "application/sparql-results+json", + "json-ld": "application/ld+json", + "xml": "application/rdf+xml", + "turtle": "text/turtle", + } if not sparql_query: return HttpResponseBadRequest("Missing 'query' parameter.") @@ -24,12 +35,37 @@ def sparql_endpoint(request): if not validate_sparql_query(sparql_query): raise SuspiciousOperation("Invalid SPARQL query.") - endpoint_url = OEKG_SPARQL_ENDPOINT_URL + # Validate and map the requested format + if response_format not in supported_formats: + return HttpResponseBadRequest(f"Unsupported format: {response_format}") - headers = {"Accept": "application/sparql-results+json"} + endpoint_url = OEKG_SPARQL_ENDPOINT_URL + headers = {"Accept": supported_formats[response_format]} response = requests.get( endpoint_url, params={"query": sparql_query}, headers=headers ) - return JsonResponse(response.json()) + # Handle different response types + content_type = supported_formats[response_format] + if content_type == "application/sparql-results+json": + return JsonResponse(response.json(), safe=False) + else: + return HttpResponse(response.content, content_type=content_type) + + +@require_GET +def sparql_metadata(request): + supported_formats = { + "json": "application/sparql-results+json", + "json-ld": "application/ld+json", + "xml": "application/rdf+xml", + "turtle": "text/turtle", + } + return JsonResponse( + { + "description": "This API accepts SPARQL queries and returns" + "the results in various formats.", + "supported_formats": supported_formats, + } + ) From a1da28eaf738e00b8488c80c9d2c40ab89edb817 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Mon, 23 Dec 2024 16:50:45 +0100 Subject: [PATCH 05/31] create a open api schema for oekg endpoint --- .../web-api/oekg-api/oekg.yaml | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/oeplatform-code/web-api/oekg-api/oekg.yaml diff --git a/docs/oeplatform-code/web-api/oekg-api/oekg.yaml b/docs/oeplatform-code/web-api/oekg-api/oekg.yaml new file mode 100644 index 000000000..1bb18b7ea --- /dev/null +++ b/docs/oeplatform-code/web-api/oekg-api/oekg.yaml @@ -0,0 +1,107 @@ +openapi: 3.0.2 +info: + title: SPARQL Query API + description: An API to execute SPARQL queries on a Jena Fuseki endpoint and retrieve results in various formats. + version: 1.0.0 +servers: + - url: https://openenergyplatform.org/ + description: Production server + - url: http://localhost:8080" + description: Development server +paths: + /oekg/sparql: + post: + summary: Execute a SPARQL query + description: | + This endpoint accepts a SPARQL query and returns the results in the specified format. + Supported query types include `SELECT`, `CONSTRUCT`, and `DESCRIBE`. The response format must be specified using the `format` parameter. + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + properties: + query: + type: string + description: The SPARQL query to execute. + example: SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10 + format: + type: string + description: | + The desired format of the SPARQL query results. Supported values are: + - `json`: SPARQL Query Results JSON (default, for SELECT queries). + - `json-ld`: JSON-LD (for CONSTRUCT/DESCRIBE queries). + - `xml`: RDF/XML (for CONSTRUCT/DESCRIBE queries). + - `turtle`: Turtle (for CONSTRUCT/DESCRIBE queries). + example: json + default: json + enum: + - json + - json-ld + - xml + - turtle + responses: + '200': + description: Successful response with query results. + content: + application/json: + schema: + type: object + description: The SPARQL query results in JSON format. + application/ld+json: + schema: + type: object + description: The SPARQL query results in JSON-LD format. + application/rdf+xml: + schema: + type: string + description: The SPARQL query results in RDF/XML format. + text/turtle: + schema: + type: string + description: The SPARQL query results in Turtle format. + '400': + description: Bad request due to invalid query or unsupported format. + content: + application/json: + schema: + type: object + properties: + error: + type: string + description: Error message. + supported_formats: + type: array + items: + type: string + description: List of supported formats. + example: + error: + Unsupported format: csv + supported_formats: ["json", "json-ld", "xml", "turtle"] + /sparql_metadata: + get: + summary: Retrieve metadata about the SPARQL API + description: Provides information about the SPARQL API, including supported response formats. + responses: + '200': + description: Successful response with API metadata. + content: + application/json: + schema: + type: object + properties: + description: + type: string + description: General description of the API. + supported_formats: + type: object + additionalProperties: + type: string + description: Mapping of format keys to MIME types. + example: + json: application/sparql-results+json + json-ld: application/ld+json + xml: application/rdf+xml + turtle: text/turtle From c6afc5fe21f6d33a8c240026ee2da25e488040ab Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Mon, 23 Dec 2024 16:52:39 +0100 Subject: [PATCH 06/31] restructure swagger ui vendor files to ease the import in more then one part of the api documentation --- .../dist/favicon-16x16.png | Bin .../dist/favicon-32x32.png | Bin .../{oedb-rest-api => }/dist/index.css | 0 .../{oedb-rest-api => }/dist/index.html | 0 .../dist/oauth2-redirect.html | 0 .../dist/swagger-initializer.js | 0 .../dist/swagger-ui-bundle.js | 0 .../dist/swagger-ui-bundle.js.map | 0 .../dist/swagger-ui-es-bundle-core.js | 0 .../dist/swagger-ui-es-bundle-core.js.map | 0 .../dist/swagger-ui-es-bundle.js | 0 .../dist/swagger-ui-es-bundle.js.map | 0 .../dist/swagger-ui-standalone-preset.js | 0 .../dist/swagger-ui-standalone-preset.js.map | 0 .../{oedb-rest-api => }/dist/swagger-ui.css | 0 .../dist/swagger-ui.css.map | 0 .../{oedb-rest-api => }/dist/swagger-ui.js | 0 .../dist/swagger-ui.js.map | 0 .../web-api/oedb-rest-api/index.md | 6 ++-- .../web-api/oedb-rest-api/swagger-ui.html | 31 ------------------ 20 files changed, 3 insertions(+), 34 deletions(-) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/favicon-16x16.png (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/favicon-32x32.png (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/index.css (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/index.html (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/oauth2-redirect.html (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-initializer.js (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui-bundle.js (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui-bundle.js.map (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui-es-bundle-core.js (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui-es-bundle-core.js.map (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui-es-bundle.js (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui-es-bundle.js.map (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui-standalone-preset.js (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui-standalone-preset.js.map (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui.css (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui.css.map (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui.js (100%) rename docs/oeplatform-code/web-api/{oedb-rest-api => }/dist/swagger-ui.js.map (100%) delete mode 100644 docs/oeplatform-code/web-api/oedb-rest-api/swagger-ui.html diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/favicon-16x16.png b/docs/oeplatform-code/web-api/dist/favicon-16x16.png similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/favicon-16x16.png rename to docs/oeplatform-code/web-api/dist/favicon-16x16.png diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/favicon-32x32.png b/docs/oeplatform-code/web-api/dist/favicon-32x32.png similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/favicon-32x32.png rename to docs/oeplatform-code/web-api/dist/favicon-32x32.png diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/index.css b/docs/oeplatform-code/web-api/dist/index.css similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/index.css rename to docs/oeplatform-code/web-api/dist/index.css diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/index.html b/docs/oeplatform-code/web-api/dist/index.html similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/index.html rename to docs/oeplatform-code/web-api/dist/index.html diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/oauth2-redirect.html b/docs/oeplatform-code/web-api/dist/oauth2-redirect.html similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/oauth2-redirect.html rename to docs/oeplatform-code/web-api/dist/oauth2-redirect.html diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-initializer.js b/docs/oeplatform-code/web-api/dist/swagger-initializer.js similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-initializer.js rename to docs/oeplatform-code/web-api/dist/swagger-initializer.js diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-bundle.js b/docs/oeplatform-code/web-api/dist/swagger-ui-bundle.js similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-bundle.js rename to docs/oeplatform-code/web-api/dist/swagger-ui-bundle.js diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-bundle.js.map b/docs/oeplatform-code/web-api/dist/swagger-ui-bundle.js.map similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-bundle.js.map rename to docs/oeplatform-code/web-api/dist/swagger-ui-bundle.js.map diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-es-bundle-core.js b/docs/oeplatform-code/web-api/dist/swagger-ui-es-bundle-core.js similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-es-bundle-core.js rename to docs/oeplatform-code/web-api/dist/swagger-ui-es-bundle-core.js diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-es-bundle-core.js.map b/docs/oeplatform-code/web-api/dist/swagger-ui-es-bundle-core.js.map similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-es-bundle-core.js.map rename to docs/oeplatform-code/web-api/dist/swagger-ui-es-bundle-core.js.map diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-es-bundle.js b/docs/oeplatform-code/web-api/dist/swagger-ui-es-bundle.js similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-es-bundle.js rename to docs/oeplatform-code/web-api/dist/swagger-ui-es-bundle.js diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-es-bundle.js.map b/docs/oeplatform-code/web-api/dist/swagger-ui-es-bundle.js.map similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-es-bundle.js.map rename to docs/oeplatform-code/web-api/dist/swagger-ui-es-bundle.js.map diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-standalone-preset.js b/docs/oeplatform-code/web-api/dist/swagger-ui-standalone-preset.js similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-standalone-preset.js rename to docs/oeplatform-code/web-api/dist/swagger-ui-standalone-preset.js diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-standalone-preset.js.map b/docs/oeplatform-code/web-api/dist/swagger-ui-standalone-preset.js.map similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui-standalone-preset.js.map rename to docs/oeplatform-code/web-api/dist/swagger-ui-standalone-preset.js.map diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui.css b/docs/oeplatform-code/web-api/dist/swagger-ui.css similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui.css rename to docs/oeplatform-code/web-api/dist/swagger-ui.css diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui.css.map b/docs/oeplatform-code/web-api/dist/swagger-ui.css.map similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui.css.map rename to docs/oeplatform-code/web-api/dist/swagger-ui.css.map diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui.js b/docs/oeplatform-code/web-api/dist/swagger-ui.js similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui.js rename to docs/oeplatform-code/web-api/dist/swagger-ui.js diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui.js.map b/docs/oeplatform-code/web-api/dist/swagger-ui.js.map similarity index 100% rename from docs/oeplatform-code/web-api/oedb-rest-api/dist/swagger-ui.js.map rename to docs/oeplatform-code/web-api/dist/swagger-ui.js.map diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/index.md b/docs/oeplatform-code/web-api/oedb-rest-api/index.md index 52df52a86..ccd43cd89 100644 --- a/docs/oeplatform-code/web-api/oedb-rest-api/index.md +++ b/docs/oeplatform-code/web-api/oedb-rest-api/index.md @@ -19,9 +19,9 @@ Below you see a draft version of the OpenAPI-based. It is the documentation for API Documentation - - - + + +
diff --git a/docs/oeplatform-code/web-api/oedb-rest-api/swagger-ui.html b/docs/oeplatform-code/web-api/oedb-rest-api/swagger-ui.html deleted file mode 100644 index dfd068ca8..000000000 --- a/docs/oeplatform-code/web-api/oedb-rest-api/swagger-ui.html +++ /dev/null @@ -1,31 +0,0 @@ - - - - - API Documentation - - - - - -
- - - From c4c5d02cfe8b26f3b7c298f02cf484da5bfa3abd Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Mon, 23 Dec 2024 17:01:46 +0100 Subject: [PATCH 07/31] update changelog --- versions/changelogs/current.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/versions/changelogs/current.md b/versions/changelogs/current.md index a90e38c5a..bbc6b2ae9 100644 --- a/versions/changelogs/current.md +++ b/versions/changelogs/current.md @@ -8,7 +8,7 @@ - Removed the outdated & unmaintained references module that was intended to handle bibtex files and store them in a django model [(#1913)](https://github.com/OpenEnergyPlatform/oeplatform/pull/1913). -- Change sparql endpoint for OEKG to use the http post method to match the expected usage [(#1913)](https://github.com/OpenEnergyPlatform/oeplatform/pull/1913). +- Change sparql endpoint for OEKG to use the http post method to match the expected usage. The OEKG API is also extended to return data in common rdf/graph formats like tutle or json ld [(#1928)](https://github.com/OpenEnergyPlatform/oeplatform/pull/1928). - Extract header/footer template [(#1914)](https://github.com/OpenEnergyPlatform/oeplatform/pull/1914) @@ -17,3 +17,5 @@ ## Bugs ## Documentation updates + +- Updated documentation to simplify usage of vendor software swagger ui and update the documentation on scenario bundles. Add documentation on how to use the updated OEKG web API [(#1928)](https://github.com/OpenEnergyPlatform/oeplatform/pull/1928). From 80ddd46664fab9535f7b08e0e59c79927c55a698 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Mon, 6 Jan 2025 10:48:07 +0100 Subject: [PATCH 08/31] configure yasguis http requests with no effect ... comeback later --- oekg/templates/oekg/main.html | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/oekg/templates/oekg/main.html b/oekg/templates/oekg/main.html index 5b025cbd6..2a5e62779 100644 --- a/oekg/templates/oekg/main.html +++ b/oekg/templates/oekg/main.html @@ -34,13 +34,33 @@

{% block after-body-bottom-js %} + From 6703bb4c619bd0f628f70ca815e4568cd3ac6a5c Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 12:49:07 +0100 Subject: [PATCH 16/31] fix css import for sparql ui --- oekg/templates/oekg/main.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/oekg/templates/oekg/main.html b/oekg/templates/oekg/main.html index edf7cbd58..66a5e8e95 100644 --- a/oekg/templates/oekg/main.html +++ b/oekg/templates/oekg/main.html @@ -2,7 +2,7 @@ {% load static %} {% block after-head %} - + {% endblock after-head %} {% block site-header %} From c031524f5fe5df7fbc1ad472423856ac1b82bdad Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 12:49:30 +0100 Subject: [PATCH 17/31] rename api view to more specific naming --- api/urls.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/urls.py b/api/urls.py index 23c58eb7f..956906767 100644 --- a/api/urls.py +++ b/api/urls.py @@ -190,7 +190,7 @@ path("oevkg-query", views.oevkg_search), re_path( r"^v0/oekg/sparql/?$", - views.SparqlAPIView.as_view(), + views.OekgSparqlAPIView.as_view(), name="oekg-sparql-http-api", ), re_path( From f509e511fb68b085a13cddff05b031fac3f0dde6 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 12:49:57 +0100 Subject: [PATCH 18/31] rename api view to more specific naming --- api/views.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/views.py b/api/views.py index 471abd5f4..dc4b4abbf 100644 --- a/api/views.py +++ b/api/views.py @@ -1511,7 +1511,7 @@ def oeo_search(request): return JsonResponse(res, safe=False) -class SparqlAPIView(APIView): +class OekgSparqlAPIView(APIView): authentication_classes = [TokenAuthentication] permission_classes = [IsAuthenticated] From 0a1767219a7ec7945e4c676c40bd0b251e83ddf7 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 12:51:10 +0100 Subject: [PATCH 19/31] OEKG Feature: - add timeout to sparql query execution method - add deprecation notice to function --- oekg/utils.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/oekg/utils.py b/oekg/utils.py index a2c40cbb5..9a5054ab7 100644 --- a/oekg/utils.py +++ b/oekg/utils.py @@ -35,7 +35,7 @@ def execute_sparql_query(sparql_query, response_format): # Execute the SPARQL query response = requests.post( - endpoint_url, data={"query": sparql_query}, headers=headers + endpoint_url, data={"query": sparql_query}, headers=headers, timeout=10 ) return response.content, SUPPORTED_FORMATS[response_format] @@ -44,6 +44,9 @@ def execute_sparql_query(sparql_query, response_format): def validate_sparql_query(query): """ Validate the SPARQL query to prevent injection attacks. + + Note: not in use currently, keep for later. Review and remove if + deprecated. """ # Basic length check From 77e6b476d115d2900c8a9b8fce2548497759ef1e Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 13:43:25 +0100 Subject: [PATCH 20/31] OEKG-API: add check to avoid update/delete queries which do not have a effect --- api/views.py | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/api/views.py b/api/views.py index 13c519e8c..8f4ed15d1 100644 --- a/api/views.py +++ b/api/views.py @@ -31,11 +31,9 @@ from omi.dialects.oep.compiler import JSONCompiler from omi.structure import OEPMetadata from rest_framework import generics, status - from rest_framework.authentication import TokenAuthentication from rest_framework.exceptions import ValidationError from rest_framework.permissions import IsAuthenticated - from rest_framework.response import Response from rest_framework.views import APIView @@ -59,8 +57,11 @@ from dataedit.views import get_tag_keywords_synchronized_metadata, schema_whitelist from factsheet.permission_decorator import post_only_if_user_is_owner_of_scenario_bundle from modelview.models import Energyframework, Energymodel -from oekg.utils import execute_sparql_query - +from oekg.utils import ( + execute_sparql_query, + process_datasets_sparql_query, + validate_public_sparql_query, +) from oeplatform.settings import PLAYGROUNDS, UNVERSIONED_SCHEMAS, USE_LOEP, USE_ONTOP if USE_LOEP: @@ -1525,6 +1526,11 @@ def post(self, request): sparql_query = request.data.get("query", "") response_format = request.data.get("format", "json") # Default format + if not validate_public_sparql_query(sparql_query): + raise ValidationError( + "Invalid SPARQL query. Update/delete queries are not allowed." + ) + try: content, content_type = execute_sparql_query(sparql_query, response_format) except ValueError as e: From b2f08678437e50decd8e10906cd2adf6e42dd4f3 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 13:44:01 +0100 Subject: [PATCH 21/31] OEKG-UI: remove deprecated test --- oekg/tests.py | 36 +++++++++--------------------------- 1 file changed, 9 insertions(+), 27 deletions(-) diff --git a/oekg/tests.py b/oekg/tests.py index d63a1699d..eb1e6a63d 100644 --- a/oekg/tests.py +++ b/oekg/tests.py @@ -1,5 +1,5 @@ import unittest -from unittest.mock import Mock, patch +from unittest.mock import patch from django.test import Client, TestCase from django.urls import reverse @@ -8,19 +8,14 @@ class SparqlEndpointTest(TestCase): def setUp(self): self.client = Client() - self.endpoint_url = reverse( - "sparql_endpoint" - ) # Ensure your URL name matches the one in your urls.py - - @patch("requests.post") - def test_valid_sparql_query(self, mock_post): - mock_response = Mock() - mock_response.status_code = 200 - mock_response.json.return_value = { - "head": {"vars": ["sub", "pred", "obj"]}, - "results": {"bindings": []}, - } - mock_post.return_value = mock_response + self.endpoint_url = reverse("sparql_endpoint") + + @patch("oekg.utils.execute_sparql_query") + def test_valid_sparql_query(self, mock_execute_sparql_query): + mock_execute_sparql_query.return_value = ( + '{"head": {"vars": ["sub", "pred", "obj"]}, "results": {"bindings": []}}', + "application/sparql-results+json", + ) query = """ PREFIX rdf: @@ -37,19 +32,6 @@ def test_valid_sparql_query(self, mock_post): self.assertIn("head", json_response) self.assertIn("results", json_response) - @patch("requests.post") - def test_invalid_sparql_query_delete(self, mock_post): - query = """ - DELETE WHERE { - ?sub ?pred ?obj . - } - """ - - response = self.client.post(self.endpoint_url, {"query": query}) - self.assertEqual( - response.status_code, 400 - ) # Expecting 400 Bad Request for invalid queries - if __name__ == "__main__": unittest.main() From 77e075e462813215d98f496977ab153a5af2b182 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 13:44:33 +0100 Subject: [PATCH 22/31] OEKG-API: simplify valid sparql query test function --- oekg/utils.py | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/oekg/utils.py b/oekg/utils.py index 7ffa70638..f7960cecd 100644 --- a/oekg/utils.py +++ b/oekg/utils.py @@ -2,9 +2,9 @@ import requests -from oeplatform.settings import OEKG_SPARQL_ENDPOINT_URL from oekg.sparqlModels import DatasetConfig from oekg.sparqlQuery import add_datasets_to_scenario, scenario_in_bundle +from oeplatform.settings import OEKG_SPARQL_ENDPOINT_URL # Whitelist of supported formats SUPPORTED_FORMATS = { @@ -43,8 +43,6 @@ def execute_sparql_query(sparql_query, response_format): return response.content, SUPPORTED_FORMATS[response_format] - - def validate_public_sparql_query(query): """ Validate the SPARQL query to prevent injection attacks. @@ -53,18 +51,6 @@ def validate_public_sparql_query(query): deprecated. """ - # Basic length check - if not query or len(query) > 10000: # Set an appropriate limit for your use case - return False - - # Basic SPARQL syntax check using a regular expression (this is a simplistic check) - pattern = re.compile( - r"^\s*(PREFIX\s+[^\s]+:\s*<[^>]+>\s*)*(SELECT|CONSTRUCT|ASK|DESCRIBE)\s+", - re.IGNORECASE, - ) - if not pattern.match(query): - return False - # Check for disallowed keywords (e.g., DROP, DELETE, INSERT) disallowed_keywords = ["DROP", "DELETE", "INSERT"] for keyword in disallowed_keywords: From e221d5f100a47c061275b40b3bc0cccffb2cbc05 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 13:45:02 +0100 Subject: [PATCH 23/31] OEKG-UI: cleanup view module and enhance error messages --- oekg/views.py | 56 +++++++++------------------------------------------ 1 file changed, 9 insertions(+), 47 deletions(-) diff --git a/oekg/views.py b/oekg/views.py index 05fb66e52..08196a090 100644 --- a/oekg/views.py +++ b/oekg/views.py @@ -7,10 +7,6 @@ from oekg.utils import execute_sparql_query -from oekg.utils import validate_public_sparql_query -from oeplatform.settings import OEKG_SPARQL_ENDPOINT_URL - - @login_required def main_view(request): @@ -19,13 +15,14 @@ def main_view(request): return response -# TODO: This endpoint requires a CSRF token, to be usable via a -# https call using CURL or requests (what the user expects when using a web-api) -# this endpoint must also accessible using the API token via the RestFramework. @require_POST def sparql_endpoint(request): """ - Public SPARQL endpoint. Must only allow read queries. + Internal SPARQL endpoint. Must only allow read queries. Intended to be use + with a djago app frontend as it requires an CSRF token. + + Note: The http based oekg sparql endpoint is implemented in api/views.py + OekgSparqlAPIView. It is usable by providing a valid API key in the request """ sparql_query = request.POST.get("query", "") response_format = request.POST.get("format", "json") # Default format @@ -33,7 +30,10 @@ def sparql_endpoint(request): try: content, content_type = execute_sparql_query(sparql_query, response_format) except ValueError as e: - return HttpResponseBadRequest(str(e)) + return HttpResponseBadRequest( + f"{str(e)}. Please provide a valid SPARQL query." + "This does not include update/delete queries." + ) if content_type == "application/sparql-results+json": return JsonResponse(json.loads(content), safe=False) @@ -41,44 +41,6 @@ def sparql_endpoint(request): return HttpResponse(content, content_type=content_type) -# def sparql_endpoint(request): -# sparql_query = request.POST.get("query", "") -# response_format = request.POST.get("format", "json") # Default format - -# # Whitelist of supported formats -# supported_formats = { -# "json": "application/sparql-results+json", -# "json-ld": "application/ld+json", -# "xml": "application/rdf+xml", -# "turtle": "text/turtle", -# } - -# if not sparql_query: -# return HttpResponseBadRequest("Missing 'query' parameter.") - -# if not validate_sparql_query(sparql_query): -# raise SuspiciousOperation("Invalid SPARQL query.") - -# # Validate and map the requested format -# if response_format not in supported_formats: -# return HttpResponseBadRequest(f"Unsupported format: {response_format}") - - -# endpoint_url = OEKG_SPARQL_ENDPOINT_URL -# headers = {"Accept": supported_formats[response_format]} - -# response = requests.post( -# endpoint_url, data={"query": sparql_query}, headers=headers -# ) - -# # Handle different response types -# content_type = supported_formats[response_format] -# if content_type == "application/sparql-results+json": -# return JsonResponse(response.json(), safe=False) -# else: -# return HttpResponse(response.content, content_type=content_type) - - @require_GET def sparql_metadata(request): supported_formats = { From d04445f20ab1b6eb04731e6542857c7852709183 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 13:51:11 +0100 Subject: [PATCH 24/31] OEKG-UI: enhance error message --- oekg/utils.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/oekg/utils.py b/oekg/utils.py index f7960cecd..d13c0c249 100644 --- a/oekg/utils.py +++ b/oekg/utils.py @@ -40,6 +40,12 @@ def execute_sparql_query(sparql_query, response_format): endpoint_url, data={"query": sparql_query}, headers=headers, timeout=10 ) + if response.status_code != 200: + raise ValueError( + f"Failed to execute SPARQL query. Reason: {response.reason}," + f"Status Code {response.status_code}." + ) + return response.content, SUPPORTED_FORMATS[response_format] From 5bc42d109ebf3dd0a810faa23c266404e7b37fae Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 14:01:34 +0100 Subject: [PATCH 25/31] OEKG API: update docs --- docs/oeplatform-code/web-api/oekg-api/index.md | 6 +++--- docs/oeplatform-code/web-api/oekg-api/oekg.yaml | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/oeplatform-code/web-api/oekg-api/index.md b/docs/oeplatform-code/web-api/oekg-api/index.md index a8e82e053..2652d61cd 100644 --- a/docs/oeplatform-code/web-api/oekg-api/index.md +++ b/docs/oeplatform-code/web-api/oekg-api/index.md @@ -4,20 +4,20 @@ In this document we describe how you can access the contents of the OEKG via Web ### The SPARQL endpoint for OEKG -`https://openenergyplatform.org/oekg/sparql/` +`https://openenergyplatform.org/api/v0/oekg/sparql/` Here is an example of how to query the Open Energy Knowledge Graph (OEKG) using SPARQL using python and the requests library for http requests. ```python import requests -sparql_endpoint = "https://openenergy-platform.org/oekg/sparql/" +sparql_endpoint = "https://openenergy-platform.org/api/v0/oekg/sparql/" payload = { "query": """SELECT ?s ?p ?o WHERE { ?s ?p ?o }""" - "format": "json-ld" + "format": "json" } r = requests.post(url=sparql_endpoint, json=payload) diff --git a/docs/oeplatform-code/web-api/oekg-api/oekg.yaml b/docs/oeplatform-code/web-api/oekg-api/oekg.yaml index 1bb18b7ea..21e8b015d 100644 --- a/docs/oeplatform-code/web-api/oekg-api/oekg.yaml +++ b/docs/oeplatform-code/web-api/oekg-api/oekg.yaml @@ -1,15 +1,15 @@ openapi: 3.0.2 info: title: SPARQL Query API - description: An API to execute SPARQL queries on a Jena Fuseki endpoint and retrieve results in various formats. + description: An API to execute SPARQL queries on a Jena Fuseki endpoint and retrieve results in various formats. The formats are currently experimental as only json or XML is returned properly. You might experience escaped stings in the return format. version: 1.0.0 servers: - url: https://openenergyplatform.org/ description: Production server - - url: http://localhost:8080" + - url: http://localhost:8000" description: Development server paths: - /oekg/sparql: + /api/v0/oekg/sparql: post: summary: Execute a SPARQL query description: | From 97e4f147da7090dcbb51adf0ddb72a89e67b5b58 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 14:09:26 +0100 Subject: [PATCH 26/31] OEKG-API docs: add info on Authorization --- docs/oeplatform-code/web-api/oekg-api/oekg.yaml | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/oeplatform-code/web-api/oekg-api/oekg.yaml b/docs/oeplatform-code/web-api/oekg-api/oekg.yaml index 21e8b015d..b170f7fac 100644 --- a/docs/oeplatform-code/web-api/oekg-api/oekg.yaml +++ b/docs/oeplatform-code/web-api/oekg-api/oekg.yaml @@ -8,6 +8,13 @@ servers: description: Production server - url: http://localhost:8000" description: Development server +components: + securitySchemes: + TokenAuth: + type: apiKey + in: header + name: Authorization + description: "Token-based authentication using Django REST Framework's token authentication. Include 'Token ' in the Authorization header." paths: /api/v0/oekg/sparql: post: @@ -15,10 +22,11 @@ paths: description: | This endpoint accepts a SPARQL query and returns the results in the specified format. Supported query types include `SELECT`, `CONSTRUCT`, and `DESCRIBE`. The response format must be specified using the `format` parameter. + Please provide your API Token as Authorization header. The token can be obtained from your Profile on the Open Energy Platform. requestBody: required: true content: - application/x-www-form-urlencoded: + application/json: schema: type: object properties: From d2a38f52a2e32d5cfd629258d8657f2797dc5109 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 16:11:12 +0100 Subject: [PATCH 27/31] External URLS: Update urls and add links to oekg api docs --- oeplatform/settings.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/oeplatform/settings.py b/oeplatform/settings.py index 3bead7421..1f04b58ff 100644 --- a/oeplatform/settings.py +++ b/oeplatform/settings.py @@ -90,7 +90,8 @@ "tutorials_wizard": "https://openenergyplatform.github.io/academy/tutorials/99_other/wizard/", # noqa E501 "tutorials_create_database_conform_data": "https://openenergyplatform.github.io/academy/tutorials/99_other/database_data/", # noqa E501 "tutorials_oemetadata": "https://openenergyplatform.github.io/academy/tutorials/99_other/getting_started_with_OEMetadata/", # noqa E501 - "readthedocs": "https://openenergyplatform.github.io/oeplatform/oeplatform-code/web-api/oedb-rest-api/", + "tutorials_oemetabuilder": "https://openenergyplatform.github.io/academy/tutorials/99_other/oemetadata/", # noqa E501 + "readthedocs": "https://openenergyplatform.github.io/oeplatform/oeplatform-code/web-api/oedb-rest-api/", # noqa E501 "mkdocs": "https://openenergyplatform.github.io/oeplatform/", "compendium": "https://openenergyplatform.github.io/organisation/", "tib_terminology_service": "https://terminology.tib.eu/ts/collections", @@ -103,9 +104,10 @@ # Kept this separate for now to avoid messing with the other list ... # TODO move to EXTERNAL_URLS if possible DOCUMENTATION_LINKS = { - "oeo_setup": "https://openenergyplatform.github.io/oeplatform/install-and-documentation/install/installation/#3-setup-the-openenergyontology-integration", # noqa:E501 - "oeo_ext_setup": "https://openenergyplatform.github.io/oeplatform/install-and-documentation/install/installation/#62-setup-the-oeo-extended-app", # noqa:E501 - "oemetabuilder": "https://openenergyplatform.github.io/oeplatform/install-and-documentation/oeplatform-code/features/metaBuilder/", # noqa:E501 + "oeo_setup": "https://openenergyplatform.github.io/oeplatform/installation/guides/installation/#3-setup-the-openenergyontology-integration", # noqa:E501 + "oeo_ext_setup": "https://openenergyplatform.github.io/oeplatform/installation/guides/installation/#62-setup-the-oeo-extended-app", # noqa:E501 + "oemetabuilder": "https://openenergyplatform.github.io/oeplatform/oeplatform-code/features/metaBuilder/", # noqa:E501 + "oekg_api": "https://openenergyplatform.github.io/oeplatform/oeplatform-code/web-api/oekg-api/", # noqa:E501 } From 358029d1c0783c76a38675e7290c84753f1c5606 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 16:12:46 +0100 Subject: [PATCH 28/31] change oemetabuilder info links to oemtabuilder tutorial --- dataedit/views.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/dataedit/views.py b/dataedit/views.py index e4e80600d..5cb55bcdf 100644 --- a/dataedit/views.py +++ b/dataedit/views.py @@ -297,7 +297,7 @@ def listschemas(request): "schemas": schemas, "query": searched_query_string, "tags": searched_tag_ids, - "doc_oem_builder_link": DOCUMENTATION_LINKS["oemetabuilder"], + "doc_oem_builder_link": EXTERNAL_URLS["tutorials_oemetabuilder"], }, ) @@ -1856,6 +1856,7 @@ def get(self, request, schema, table): "doc_links": DOCUMENTATION_LINKS, "oem_key_desc": EXTERNAL_URLS["oemetadata_key_description"], "oemetadata_tutorial": EXTERNAL_URLS["tutorials_oemetadata"], + "oemetabuilder_tutorial": EXTERNAL_URLS["tutorials_oemetabuilder"], } return render( @@ -1873,6 +1874,7 @@ def get(self, request): ), "oem_key_desc": EXTERNAL_URLS["oemetadata_key_description"], "oemetadata_tutorial": EXTERNAL_URLS["tutorials_oemetadata"], + "oemetabuilder_tutorial": EXTERNAL_URLS["tutorials_oemetabuilder"], } return render( request, From b27aef4cf0cbc98cc125324aee567847217183f2 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 16:13:07 +0100 Subject: [PATCH 29/31] metaBuilder: add link to oemetabuilder tutorial --- dataedit/templates/dataedit/meta_edit.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dataedit/templates/dataedit/meta_edit.html b/dataedit/templates/dataedit/meta_edit.html index f9eedb042..879c54283 100644 --- a/dataedit/templates/dataedit/meta_edit.html +++ b/dataedit/templates/dataedit/meta_edit.html @@ -30,7 +30,7 @@


Find a detailed description for all fields of the OEMetaData visible on GitHub. - For a brief introduction on how to work with the oemetadata and the OEMetaBuilder tool find our tutorial in the academy. + For a brief introduction on how to work with the oemetadata and the OEMetaBuilder tool find our tutorial in the academy.
From bc51f1159a7ab489d5aa1a2d53adae46ce424634 Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 16:13:54 +0100 Subject: [PATCH 30/31] docs: add missing instructions on how to setup the oeo_ext app --- docs/installation/guides/installation.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/installation/guides/installation.md b/docs/installation/guides/installation.md index 966adf32c..ebe53cca9 100644 --- a/docs/installation/guides/installation.md +++ b/docs/installation/guides/installation.md @@ -277,6 +277,14 @@ The oeo-viewer is a visualization tool for our OEO ontology and it is under deve After these steps, a `static` folder inside `oep-website/oeplatform/oeo_viewer/` will be created which includes the results of the `npm run build` command. These files are necessary for the oeo-viewer. +### 6.2 Setup the oeo extended app + +The oeo extended is used to create new ontology classes on the fly while annotating a oemetadata document. Especially if one wants to annotate composed units which are more complex than a simple meter or square meter unit. These composed units are stored separate from the OEO ontology in the OEOX which is located in its own owl file. + +The use case described above requires to setup the oeo extended template file in the `media/` directory. We offer a template file to simplify this task. + + cp oeo_ext/oeo_extended_store/oeox_template/oeo_ext_template_empty.owl media/oeo_ext/oeo_ext.owl + ## 7 Setup the Scenario-Bundles app !!! note "Optional Step" From ece28cd9f047225c5d7e7ef6aa00dca312961f0a Mon Sep 17 00:00:00 2001 From: jh-RLI Date: Thu, 20 Feb 2025 16:14:38 +0100 Subject: [PATCH 31/31] oekg-ui: add link to oekg api docs --- oekg/templates/oekg/main.html | 2 +- oekg/views.py | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/oekg/templates/oekg/main.html b/oekg/templates/oekg/main.html index 66a5e8e95..0043a9473 100644 --- a/oekg/templates/oekg/main.html +++ b/oekg/templates/oekg/main.html @@ -12,7 +12,7 @@

OEKG Sparql Query

- + Here you can query the Open Energy Knowledge Graph (OEKG) using SPARQL. You can also use our http api, have a look at the documentation.
{% endblock site-header %} diff --git a/oekg/views.py b/oekg/views.py index 08196a090..463cad24d 100644 --- a/oekg/views.py +++ b/oekg/views.py @@ -6,11 +6,14 @@ from django.views.decorators.http import require_GET, require_POST from oekg.utils import execute_sparql_query +from oeplatform.settings import DOCUMENTATION_LINKS @login_required def main_view(request): - response = render(request, "oekg/main.html") + response = render( + request, "oekg/main.html", context={"oekg_api": DOCUMENTATION_LINKS["oekg_api"]} + ) response["Content-Type"] = "text/html; charset=utf-8" return response