From 9cf1a50f470b776a4b0255f3a5adbb66797284ff Mon Sep 17 00:00:00 2001 From: Serafeim Chatzopoulos Date: Fri, 5 Jul 2024 17:55:58 +0300 Subject: [PATCH 1/7] Add overview of the graph API --- docs/apis/graph-api/get-single-entities.md | 2 ++ docs/apis/graph-api/overview.md | 22 +++++++++++++++++++ .../search-entities/filter-search-results.md | 2 ++ .../graph-api/search-entities/overview.md | 1 + .../graph-api/search-entities/pagination.md | 1 + .../search-entities/sort-search-results.md | 1 + docs/apis/home.md | 9 ++++---- sidebars.js | 18 +++++++++++++++ 8 files changed, 52 insertions(+), 4 deletions(-) create mode 100644 docs/apis/graph-api/get-single-entities.md create mode 100644 docs/apis/graph-api/overview.md create mode 100644 docs/apis/graph-api/search-entities/filter-search-results.md create mode 100644 docs/apis/graph-api/search-entities/overview.md create mode 100644 docs/apis/graph-api/search-entities/pagination.md create mode 100644 docs/apis/graph-api/search-entities/sort-search-results.md diff --git a/docs/apis/graph-api/get-single-entities.md b/docs/apis/graph-api/get-single-entities.md new file mode 100644 index 0000000..df00bf2 --- /dev/null +++ b/docs/apis/graph-api/get-single-entities.md @@ -0,0 +1,2 @@ +# Get single entities + diff --git a/docs/apis/graph-api/overview.md b/docs/apis/graph-api/overview.md new file mode 100644 index 0000000..f8d9c76 --- /dev/null +++ b/docs/apis/graph-api/overview.md @@ -0,0 +1,22 @@ +# Graph API + +The OpenAIRE Graph API provides a comprehensive way for developers to explore the [OpenAIRE Graph](https://graph.openaire.eu/), a vast interconnected dataset that aggregates metadata from a wide range of scholarly resources. +The Graph API offers endpoints for accessing and querying this interconnected dataset, enabling users to retrieve detailed information on research products, organizations, data sources, and projects. + +You can access the Swagger documentation of the Graph API [here](https://openaire-api.athenarc.gr/swagger-ui/index.html#/). + + +Please note that the Graph API: + +- is intended for data discovery and exploration; if you are interested in downloading the full OpenAIRE Graph dataset, please navigate [here](../../downloads/full-graph). +- adhers to the [terms of use](../terms.md) of the OpenAIRE public APIs - certain (rate limit) restrictions apply. + +## Learn more + +Please use the following links to learn more about the Graph API: + +- [Get single entities](./get-single-entities) - Retrieve detailed information on a single entity. +- [Search entities](./search-entities/overview) - Retrieve a list of entities based on specific search criteria. + - [Filter search results](./search-entities/filter-search-results) - Filter search results based on specific criteria. + - [Sort search results](./search-entities/sort-search-results) - Sort search results based on specific criteria. + - [Pagination](./search-entities/pagination) - Retrieve a subset of search results. diff --git a/docs/apis/graph-api/search-entities/filter-search-results.md b/docs/apis/graph-api/search-entities/filter-search-results.md new file mode 100644 index 0000000..2473d2f --- /dev/null +++ b/docs/apis/graph-api/search-entities/filter-search-results.md @@ -0,0 +1,2 @@ +# Filter search results + diff --git a/docs/apis/graph-api/search-entities/overview.md b/docs/apis/graph-api/search-entities/overview.md new file mode 100644 index 0000000..e6c67e4 --- /dev/null +++ b/docs/apis/graph-api/search-entities/overview.md @@ -0,0 +1 @@ +# Search entities \ No newline at end of file diff --git a/docs/apis/graph-api/search-entities/pagination.md b/docs/apis/graph-api/search-entities/pagination.md new file mode 100644 index 0000000..4122fb7 --- /dev/null +++ b/docs/apis/graph-api/search-entities/pagination.md @@ -0,0 +1 @@ +# Pagination \ No newline at end of file diff --git a/docs/apis/graph-api/search-entities/sort-search-results.md b/docs/apis/graph-api/search-entities/sort-search-results.md new file mode 100644 index 0000000..91ff48c --- /dev/null +++ b/docs/apis/graph-api/search-entities/sort-search-results.md @@ -0,0 +1 @@ +# Sort search results \ No newline at end of file diff --git a/docs/apis/home.md b/docs/apis/home.md index 2fb15c0..aa25e6e 100644 --- a/docs/apis/home.md +++ b/docs/apis/home.md @@ -1,9 +1,10 @@ # Public APIs The OpenAIRE Graph data are accessible through various public APIs. More specifically, the following APIs are currently provided: -* [Search API](./search-api/search-api.md) (an API to search for research products and projects) -* [ScholeXplorer API](https://api.scholexplorer.openaire.eu/swagger-ui/index.html?urls.primaryName=Scholexplorer%20API%20V2.0) (an API offering dataset-publication & dataset-dataset links) -* [DSpace & EPrints API](./dspace-eprints-api.md) (an API to offer custom access to metadata for projects funded by a selection of international funders for DSpace and EPrints platforms) -* [Broker API](./broker-api.md) (an API to enrich metadata for repositories, publishers, and aggregators) +* [Graph API](./graph-api/overview) - an API to explore the OpenAIRE Graph +* [Search API](./search-api/search-api.md) - an API to search for research products and projects +* [ScholeXplorer API](https://api.scholexplorer.openaire.eu/swagger-ui/index.html?urls.primaryName=Scholexplorer%20API%20V2.0) - an API offering dataset-publication & dataset-dataset links +* [DSpace & EPrints API](./dspace-eprints-api.md) - an API to offer custom access to metadata for projects funded by a selection of international funders for DSpace and EPrints platforms +* [Broker API](./broker-api.md) - an API to enrich metadata for repositories, publishers, and aggregators It is also worth mentioning that, between 2015 and 2023 a LOD API was being provided but the respective service has been discontinued. Old LOD datasets can be found on Zenodo [here](https://zenodo.org/records/4587369). \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 17283d7..a195bf5 100644 --- a/sidebars.js +++ b/sidebars.js @@ -58,6 +58,24 @@ const sidebars = { label: "Public APIs", link: {type: 'doc', id: 'apis/home'}, items: [ + { + type: 'category', + label: "Graph API", + link: { type: 'doc', id: 'apis/graph-api/overview' }, + items: [ + { type: 'doc', id: 'apis/graph-api/get-single-entities' }, + { + type: 'category', + label: "Search entities", + link: { type: 'doc', id: 'apis/graph-api/search-entities/overview' }, + items: [ + { type: 'doc', id: 'apis/graph-api/search-entities/filter-search-results' }, + { type: 'doc', id: 'apis/graph-api/search-entities/sort-search-results' }, + { type: 'doc', id: 'apis/graph-api/search-entities/pagination' }, + ] + } + ] + }, { type: 'category', label: "Search API", From 94e96f64b53144b07029bcc5cb86b2efce17e9a2 Mon Sep 17 00:00:00 2001 From: Serafeim Chatzopoulos Date: Fri, 5 Jul 2024 19:38:08 +0300 Subject: [PATCH 2/7] Add get single entities page --- docs/apis/graph-api/get-single-entities.md | 105 ++++++++++++++++++ docs/apis/graph-api/overview.md | 9 +- .../search-entities/filter-search-results.md | 3 + .../graph-api/search-entities/overview.md | 6 +- .../graph-api/search-entities/pagination.md | 6 +- .../search-entities/sort-search-results.md | 6 +- 6 files changed, 131 insertions(+), 4 deletions(-) diff --git a/docs/apis/graph-api/get-single-entities.md b/docs/apis/graph-api/get-single-entities.md index df00bf2..3b7f13c 100644 --- a/docs/apis/graph-api/get-single-entities.md +++ b/docs/apis/graph-api/get-single-entities.md @@ -1,2 +1,107 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Get single entities +This is a guide on how to retrieve detailed information on a single entity using the OpenAIRE Graph API. + +## Endpoints +Currently, the Graph API supports the following entity types: + +- Research products - endpoint: `GET /researchProducts/{id}` +- Organizations - endpoint: `GET /organizations/{id}` +- Data sources - endpoint: `GET /dataSources/{id}` +- Projects - endpoint: `GET /projects/{id}` + +It is evident that you can retrieve the data of a single entity by providing the entity's unique OpenAIRE identifier (id) in the corresponding endpoint. +You can find more details about OpenAIRE identifiers [here](../../data-model/pids-and-identifiers). + +## Response +The response of the Graph API is a [Research Product](../../data-model/entities/research-product), [Organization](../../data-model/entities/organization), [Data Source](../../data-model/entities/data-source), or [Project](../../data-model/entities/project), depending on the endpoint used. + +## Examples +Here are some examples of how to retrieve single entity records using the Graph API. Please, navigate through the tabs to see the examples for each entity type. + +### Research products + + + +Get the research product with the OpenAIRE identifier `doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108`: + +[`https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108`](https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108) + +or using code: + + + + + +```bash +curl -X GET "https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108" -H "accept: application/json" +``` + + + + +```python +import requests + +url = "https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108" +headers = { + "accept": "application/json" +} + +response = requests.get(url, headers=headers) + +if response.status_code == 200: + print(response.json()) +else: + print(f"Request failed with status code {response.status_code}") +``` + + + + +This API call will return all the data of the research product with the given identifier: + +```json +{ + "id": "doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108", + "mainTitle": "Political conservatism as motivated social cognition.", + "description": [ + "Analyzing political conservatism as motivated social cognition integrates theories of personality (authoritarianism, dogmatism-intolerance of ambiguity), epistemic and existential needs (for closure, regulatory focus, terror management), and ideological rationalization (social dominance, system justification). A meta-analysis (88 samples, 12 countries, 22,818 cases) confirms that several psychological variables predict political conservatism: death anxiety (weighted mean r = .50); system instability (.47); dogmatism-intolerance of ambiguity (.34); openness to experience (-.32); uncertainty tolerance (-.27); needs for order, structure, and closure (.26); integrative complexity (-.20); fear of threat and loss (.18); and self-esteem (-.09). The core ideology of conservatism stresses resistance to change and justification of inequality and is motivated by needs that vary situationally and dispositionally to manage uncertainty and threat." + ], + "author": [ + { + "fullName": "John T, Jost", + "name": "John T", + "surname": "Jost", + "rank": 1, + "pid": { + "id": { + "scheme": "orcid", + "value": "0000-0002-2844-4645" + }, + "provenance": null + } + } + ], + "type": "publication", + "publicationDate": "2003-01-01", + "publisher": "American Psychological Association (APA)", + "source": [ + "Crossref" + ], + "pid": [ + { + "scheme": "Digital Object Identifier", + "value": "10.1037/0033-2909.129.3.339" + }, + { + "scheme": "PubMed ID", + "value": "12784935" + } + ], + // for brevity, the rest of the fields are omitted +} +``` \ No newline at end of file diff --git a/docs/apis/graph-api/overview.md b/docs/apis/graph-api/overview.md index f8d9c76..59b698b 100644 --- a/docs/apis/graph-api/overview.md +++ b/docs/apis/graph-api/overview.md @@ -3,9 +3,16 @@ The OpenAIRE Graph API provides a comprehensive way for developers to explore the [OpenAIRE Graph](https://graph.openaire.eu/), a vast interconnected dataset that aggregates metadata from a wide range of scholarly resources. The Graph API offers endpoints for accessing and querying this interconnected dataset, enabling users to retrieve detailed information on research products, organizations, data sources, and projects. -You can access the Swagger documentation of the Graph API [here](https://openaire-api.athenarc.gr/swagger-ui/index.html#/). +## Base URL and Swagger documentation +The base URL of the Graph API is: +``` +https://openaire-api.athenarc.gr/api +``` +You can access the API documentation in [api.openaire.eu/graph-api](https://openaire-api.athenarc.gr/swagger-ui/index.html#/). + +## Notes Please note that the Graph API: - is intended for data discovery and exploration; if you are interested in downloading the full OpenAIRE Graph dataset, please navigate [here](../../downloads/full-graph). diff --git a/docs/apis/graph-api/search-entities/filter-search-results.md b/docs/apis/graph-api/search-entities/filter-search-results.md index 2473d2f..d4dd38e 100644 --- a/docs/apis/graph-api/search-entities/filter-search-results.md +++ b/docs/apis/graph-api/search-entities/filter-search-results.md @@ -1,2 +1,5 @@ # Filter search results +:::info warning +To be completed soon, for the next beta release. +::: \ No newline at end of file diff --git a/docs/apis/graph-api/search-entities/overview.md b/docs/apis/graph-api/search-entities/overview.md index e6c67e4..280762b 100644 --- a/docs/apis/graph-api/search-entities/overview.md +++ b/docs/apis/graph-api/search-entities/overview.md @@ -1 +1,5 @@ -# Search entities \ No newline at end of file +# Search entities + +:::info warning +To be completed soon, for the next beta release. +::: \ No newline at end of file diff --git a/docs/apis/graph-api/search-entities/pagination.md b/docs/apis/graph-api/search-entities/pagination.md index 4122fb7..8c0c46f 100644 --- a/docs/apis/graph-api/search-entities/pagination.md +++ b/docs/apis/graph-api/search-entities/pagination.md @@ -1 +1,5 @@ -# Pagination \ No newline at end of file +# Pagination + +:::info warning +To be completed soon, for the next beta release. +::: \ No newline at end of file diff --git a/docs/apis/graph-api/search-entities/sort-search-results.md b/docs/apis/graph-api/search-entities/sort-search-results.md index 91ff48c..e0346a9 100644 --- a/docs/apis/graph-api/search-entities/sort-search-results.md +++ b/docs/apis/graph-api/search-entities/sort-search-results.md @@ -1 +1,5 @@ -# Sort search results \ No newline at end of file +# Sort search results + +:::info warning +To be completed soon, for the next beta release. +::: \ No newline at end of file From 0b092111e2bcfd89ac107881f53962b1e164fafd Mon Sep 17 00:00:00 2001 From: Serafeim Chatzopoulos Date: Tue, 9 Jul 2024 16:49:51 +0300 Subject: [PATCH 3/7] Finalise get single entities --- docs/apis/graph-api/get-single-entities.md | 73 ++++------------------ docs/apis/graph-api/overview.md | 7 ++- 2 files changed, 15 insertions(+), 65 deletions(-) diff --git a/docs/apis/graph-api/get-single-entities.md b/docs/apis/graph-api/get-single-entities.md index 3b7f13c..5b691cb 100644 --- a/docs/apis/graph-api/get-single-entities.md +++ b/docs/apis/graph-api/get-single-entities.md @@ -13,56 +13,24 @@ Currently, the Graph API supports the following entity types: - Data sources - endpoint: `GET /dataSources/{id}` - Projects - endpoint: `GET /projects/{id}` -It is evident that you can retrieve the data of a single entity by providing the entity's unique OpenAIRE identifier (id) in the corresponding endpoint. -You can find more details about OpenAIRE identifiers [here](../../data-model/pids-and-identifiers). +You can retrieve the data of a single entity by providing the entity's OpenAIRE identifier (id) in the corresponding endpoint. +The OpenAIRE id is the primary key of an entity in the OpenAIRE Graph. + +:::info +Note that if you want to retrieve multiple entities based on their OpenAIRE ids, you can use the [search endpoints and filter](./search-entities/filter-search-results) by the `id` field using `OR`. +::: ## Response -The response of the Graph API is a [Research Product](../../data-model/entities/research-product), [Organization](../../data-model/entities/organization), [Data Source](../../data-model/entities/data-source), or [Project](../../data-model/entities/project), depending on the endpoint used. +The response of the Graph API is a [Research product](../../data-model/entities/research-product), [Organization](../../data-model/entities/organization), [Data Source](../../data-model/entities/data-source), or [Project](../../data-model/entities/project), depending on the endpoint used. -## Examples -Here are some examples of how to retrieve single entity records using the Graph API. Please, navigate through the tabs to see the examples for each entity type. +## Example -### Research products - - - -Get the research product with the OpenAIRE identifier `doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108`: +In order to retrieve the research product with OpenAIRE id: `doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108`, +you have to perform the following API call: [`https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108`](https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108) -or using code: - - - - - -```bash -curl -X GET "https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108" -H "accept: application/json" -``` - - - - -```python -import requests - -url = "https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108" -headers = { - "accept": "application/json" -} - -response = requests.get(url, headers=headers) - -if response.status_code == 200: - print(response.json()) -else: - print(f"Request failed with status code {response.status_code}") -``` - - - - -This API call will return all the data of the research product with the given identifier: +This will return all the data of the research product with the provided identifier: ```json { @@ -71,21 +39,6 @@ This API call will return all the data of the research product with the given id "description": [ "Analyzing political conservatism as motivated social cognition integrates theories of personality (authoritarianism, dogmatism-intolerance of ambiguity), epistemic and existential needs (for closure, regulatory focus, terror management), and ideological rationalization (social dominance, system justification). A meta-analysis (88 samples, 12 countries, 22,818 cases) confirms that several psychological variables predict political conservatism: death anxiety (weighted mean r = .50); system instability (.47); dogmatism-intolerance of ambiguity (.34); openness to experience (-.32); uncertainty tolerance (-.27); needs for order, structure, and closure (.26); integrative complexity (-.20); fear of threat and loss (.18); and self-esteem (-.09). The core ideology of conservatism stresses resistance to change and justification of inequality and is motivated by needs that vary situationally and dispositionally to manage uncertainty and threat." ], - "author": [ - { - "fullName": "John T, Jost", - "name": "John T", - "surname": "Jost", - "rank": 1, - "pid": { - "id": { - "scheme": "orcid", - "value": "0000-0002-2844-4645" - }, - "provenance": null - } - } - ], "type": "publication", "publicationDate": "2003-01-01", "publisher": "American Psychological Association (APA)", @@ -96,10 +49,6 @@ This API call will return all the data of the research product with the given id { "scheme": "Digital Object Identifier", "value": "10.1037/0033-2909.129.3.339" - }, - { - "scheme": "PubMed ID", - "value": "12784935" } ], // for brevity, the rest of the fields are omitted diff --git a/docs/apis/graph-api/overview.md b/docs/apis/graph-api/overview.md index 59b698b..780d036 100644 --- a/docs/apis/graph-api/overview.md +++ b/docs/apis/graph-api/overview.md @@ -1,16 +1,16 @@ # Graph API The OpenAIRE Graph API provides a comprehensive way for developers to explore the [OpenAIRE Graph](https://graph.openaire.eu/), a vast interconnected dataset that aggregates metadata from a wide range of scholarly resources. -The Graph API offers endpoints for accessing and querying this interconnected dataset, enabling users to retrieve detailed information on research products, organizations, data sources, and projects. +The Graph API offers endpoints for accessing and querying this interconnected dataset, enabling users to retrieve detailed information on research products, data sources, organizations, and projects. ## Base URL and Swagger documentation The base URL of the Graph API is: ``` -https://openaire-api.athenarc.gr/api +https://openaire-api.athenarc.gr/ ``` -You can access the API documentation in [api.openaire.eu/graph-api](https://openaire-api.athenarc.gr/swagger-ui/index.html#/). +You can access the API Swagger documentation in [https://openaire-api.athenarc.gr/swagger-ui/index.html#/](https://openaire-api.athenarc.gr/swagger-ui/index.html#/). ## Notes Please note that the Graph API: @@ -27,3 +27,4 @@ Please use the following links to learn more about the Graph API: - [Filter search results](./search-entities/filter-search-results) - Filter search results based on specific criteria. - [Sort search results](./search-entities/sort-search-results) - Sort search results based on specific criteria. - [Pagination](./search-entities/pagination) - Retrieve a subset of search results. +- [Making requests](./making-requests) - Learn how to make requests with different programming languages. From 8b12f7bf042c9294892906fc0c9f40d3c8e93a5e Mon Sep 17 00:00:00 2001 From: Serafeim Chatzopoulos Date: Wed, 10 Jul 2024 21:22:13 +0300 Subject: [PATCH 4/7] Add search, filtering, sorting & paging using the Graph API --- docs/apis/graph-api/get-single-entities.md | 9 +- docs/apis/graph-api/making-requests.md | 33 +++ docs/apis/graph-api/overview.md | 4 +- .../search-entities/filter-search-results.md | 214 +++++++++++++++++- .../graph-api/search-entities/overview.md | 45 +++- .../graph-api/search-entities/pagination.md | 5 - .../search-entities/sort-search-results.md | 5 - .../search-entities/sorting-and-paging.md | 46 ++++ sidebars.js | 6 +- 9 files changed, 341 insertions(+), 26 deletions(-) create mode 100644 docs/apis/graph-api/making-requests.md delete mode 100644 docs/apis/graph-api/search-entities/pagination.md delete mode 100644 docs/apis/graph-api/search-entities/sort-search-results.md create mode 100644 docs/apis/graph-api/search-entities/sorting-and-paging.md diff --git a/docs/apis/graph-api/get-single-entities.md b/docs/apis/graph-api/get-single-entities.md index 5b691cb..0d82b41 100644 --- a/docs/apis/graph-api/get-single-entities.md +++ b/docs/apis/graph-api/get-single-entities.md @@ -1,6 +1,3 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - # Get single entities This is a guide on how to retrieve detailed information on a single entity using the OpenAIRE Graph API. @@ -16,8 +13,8 @@ Currently, the Graph API supports the following entity types: You can retrieve the data of a single entity by providing the entity's OpenAIRE identifier (id) in the corresponding endpoint. The OpenAIRE id is the primary key of an entity in the OpenAIRE Graph. -:::info -Note that if you want to retrieve multiple entities based on their OpenAIRE ids, you can use the [search endpoints and filter](./search-entities/filter-search-results) by the `id` field using `OR`. +:::note +Note that if you want to retrieve multiple entities based on their OpenAIRE ids, you can use the [search endpoints and filter](./search-entities/filter-search-results#or-operator) by the `id` field using `OR`. ::: ## Response @@ -28,7 +25,7 @@ The response of the Graph API is a [Research product](../../data-model/entities/ In order to retrieve the research product with OpenAIRE id: `doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108`, you have to perform the following API call: -[`https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108`](https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108) +[https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108](https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108) This will return all the data of the research product with the provided identifier: diff --git a/docs/apis/graph-api/making-requests.md b/docs/apis/graph-api/making-requests.md new file mode 100644 index 0000000..3df7c0d --- /dev/null +++ b/docs/apis/graph-api/making-requests.md @@ -0,0 +1,33 @@ +# Making requests + +or using code: + + + + + +```bash +curl -X GET "https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108" -H "accept: application/json" +``` + + + + +```python +import requests + +url = "https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108" +headers = { + "accept": "application/json" +} + +response = requests.get(url, headers=headers) + +if response.status_code == 200: + print(response.json()) +else: + print(f"Request failed with status code {response.status_code}") +``` + + + \ No newline at end of file diff --git a/docs/apis/graph-api/overview.md b/docs/apis/graph-api/overview.md index 780d036..a9f8031 100644 --- a/docs/apis/graph-api/overview.md +++ b/docs/apis/graph-api/overview.md @@ -25,6 +25,6 @@ Please use the following links to learn more about the Graph API: - [Get single entities](./get-single-entities) - Retrieve detailed information on a single entity. - [Search entities](./search-entities/overview) - Retrieve a list of entities based on specific search criteria. - [Filter search results](./search-entities/filter-search-results) - Filter search results based on specific criteria. - - [Sort search results](./search-entities/sort-search-results) - Sort search results based on specific criteria. - - [Pagination](./search-entities/pagination) - Retrieve a subset of search results. + - [Sort search results](./search-entities/sorting-and-paging#sorting) - Sort search results based on specific criteria. + - [Pagination](./search-entities/sorting-and-paging#paging) - Retrieve a subset of search results. - [Making requests](./making-requests) - Learn how to make requests with different programming languages. diff --git a/docs/apis/graph-api/search-entities/filter-search-results.md b/docs/apis/graph-api/search-entities/filter-search-results.md index d4dd38e..877bba0 100644 --- a/docs/apis/graph-api/search-entities/filter-search-results.md +++ b/docs/apis/graph-api/search-entities/filter-search-results.md @@ -1,5 +1,215 @@ # Filter search results -:::info warning -To be completed soon, for the next beta release. +Filters can be used to narrow down the search results based on specific criteria. +Filters are provided as query parameters in the request URL (see [here](./overview#endpoints) for the available search entpoints). + +Multiple filters can be provided in a single request; they should be formatted as follows: +`param1=value1¶m2=value2&...¶mN=valueN`. + +:::note +Filters are combined using the logical `AND` operator. +If a filter is provided multiple times, its values are combined using the logical `OR` operator. +For more information on how to use logical operators when searching and filtering, see [Using logical operators](#using-logical-operators). +::: + +Examples: + +- Get all research products that contain the word "covid", sorted by popularity in descending order: + + [https://openaire-api.athenarc.gr/researchProducts?search=covid&sortBy=popularity DESC](https://openaire-api.athenarc.gr/researchProducts?search=covid&sortBy=popularity%20DESC) + +- Get all publications that are published after 2019-01-01: + + [https://openaire-api.athenarc.gr/researchProducts?type=publication&fromPublicationDate=2019-01-01](https://openaire-api.athenarc.gr//researchProducts?type=publication&fromPublicationDate=2019-01-01) + +- Get the organization with the ROR id `https://ror.org/0576by029`: + + [https://openaire-api.athenarc.gr/organizations?pid=https://ror.org/0576by029](https://openaire-api.athenarc.gr/organizations?pid=https://ror.org/0576by029) + +## Available parameters + +This section provides an overview of the available parameters for each entity type. + +### Research products + +The following query parameters are available for research products: + + +| **Parameter** | **Description** | +|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **search** | Search in the content of the research product. | +| **mainTitle** | Search in the research product's main title. | +| **description** | Search in the research product's description. | +| **id** | The OpenAIRE id of the research product. | +| **pid** | The persistent identifier of the research product. | +| **originalId** | The identifier of the record at the original sources. | +| **type** | The type of the research product. One of `publication`, `dataset`, `software`, or `other` | +| **fromPublicationDate** | Gets the research products whose publication date is greater than or equal to the given date. A date formatted as `YYYY-MM-DD` | +| **toPublicationDate** | Gets the research products whose publication date is less than or equal to the given date. A date formatted as `YYYY-MM-DD` | +| **subjects** | List of subjects associated to the research product. | +| **countryCode** | The country code for the country associated with the research product. | +| **authorFullName** | The full name of the authors involved in producing this research product. | +| **authorOrcid** | The ORCiD of the authors involved in producing this research product. | +| **publisher** | The name of the entity that holds, archives, publishes prints, distributes, releases, issues, or produces the resource. +| **bestOpenAccessRightLabel** | The best open access rights among the research product's instances. One of `OPEN SOURCE`, `OPEN`, `EMBARGO`, `RESTRICTED`, `CLOSED`, `UNKNOWN` | +| **influenceClass** | Citation-based indicator that reflects the overall impact of a research product. Please, choose a class among `C1`, `C2`, `C3`, `C4`, or `C5` for top 0.01%, top 0.1%, top 1%, top 10%, and average in terms of influence respectively. | +| **impulseClass** | Citation-based indicator that reflects the initial momentum of a research product directly after its publication. Please, choose a class among `C1`, `C2`, `C3`, `C4`, or `C5` for top 0.01%, top 0.1%, top 1%, top 10%, and average in terms of impulse respectively +| **popularityClass** | Citation-based indicator that reflects current impact or attention of a research product. Please, choose a class among `C1`, `C2`, `C3`, `C4`, or `C5` for top 0.01%, top 0.1%, top 1%, top 10%, and average in terms of popularity respectively. +| **citationCountClass** | Citation-based indicator that reflects the overall impact of a research product by summing all its citations. Please, choose a class among `C1`, `C2`, `C3`, `C4`, or `C5` for top 0.01%, top 0.1%, top 1%, top 10%, and average in terms of citation count respectively. +| **instanceType** `[Only for publications]` | Retrieve publications of the given instance type. Check [here](http://api.openaire.eu/vocabularies/dnet:publication_resource) for all possible instance type values. | +| **sdg** `[Only for publications]` | Retrieves publications classified with the respective Sustainable Development Goal number. Integer in the range [1, 17] | +| **fos** `[Only for publications]` | Retrieves publications classified with a given Field of Science (FOS). A FOS classification identifier (see [here](https://explore.openaire.eu/assets/common-assets/vocabulary/fos.json) for details). | +| **isPeerReviewed** `[Only for publications]` | Indicates whether the publications are peerReviewed or not. (Boolean) | +| **isInDiamondJournal** `[Only for publications]` | Indicates whether the publication was published in a diamond journal or not. (Boolean) | +| **isPubliclyFunded** `[Only for publications]` | Indicates whether the publication was publicly funded or not. (Boolean) | +| **isGreen** `[Only for publications]` | Indicates whether the publication was published following the green open access model. (Boolean) | +| **openAccessColor** `[Only for publications]` | Specifies the Open Access color of the publication. One of `bronze`, `gold`, or `hybrid` | +| **relOrganizationId** | Retrieve research products connected to the organization (with OpenAIRE id). | +| **relCommunityId** | Retrieve research products connected to the community (with OpenAIRE id). | +| **relProjectId** | Retrieve research products connected to the project (with OpenAIRE id). | +| **relProjectCode** | Retrieve research products connected to the project with code. | +| **hasProjectRel** | Retrieve research products that are connected to a project. (Boolean) | +| **relProjectFundingShortName**| Retrieve research products connected to a project that has a funder with the given short name. | +| **relProjectFundingStreamId** | Retrieve research products connected to a project that has the given funding identifier. | +| **relHostingDataSourceId** | Retrieve research products hosted by the data source (with OpenAIRE id). | +| **relCollectedFromDatasourceId**| Retrieve research products collected from the data source (with OpenAIRE id). | +| **debugQuery** | Retrieve debug information for the search query. (Boolean) | +| **page** | Page number of the results. (Integer) | +| **pageSize** | Number of results per page. Integer in the range [1, 100] | +| **sortBy** | The field to set the sorting order of the results. Should be provided in the format `fieldname ASC\|DESC`, where fieldname is one of `relevance`, `publicationDate`, `dateOfCollection`, `influence`, `popularity`, `citationCount`, `impulse`. Multiple sorting parameters should be comma-separated. | + + +### Organizations + +The following query parameters are available for organizations: + +| **Parameter** | **Description** | +|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|**search** | Search in the content of the organization. | +|**legalName** |The legal name of the organization. | +|**legalShortName** |The legal name of the organization in short form. | +|**id** |The OpenAIRE id of the organization. | +|**pid** |The persistent identifier of the organization. | +|**countryCode** |The country code of the organization. | +|**relCommunityId** |Retrieve organizations connected to the community (with OpenAIRE id). | +|**relCollectedFromDatasourceId**|Retrieve organizations collected from the data source (with OpenAIRE id). | +|**debugQuery** |Retrieve debug information for the search query. | +|**page** |Page number of the results. | +|**pageSize** |Number of results per page. | +|**sortBy** |The field to set the sorting order of the results. Should be provided in the format `fieldname ASC\|DESC` - organizations can be only sorted by the `relevance`.| + + +### Data sources + +The following query parameters are available for data sources: + +| **Parameter** | **Description** | +|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|**search** | Search in the content of the data source. | +|**officialName** |The official name of the data source. | +|**englishName** |The English name of the data source. | +|**legalShortName** |The legal name of the organization in short form. | +|**id** |The OpenAIRE id of the data source. | +|**pid** |The persistent identifier of the data source. | +|**subjects** |List of subjects associated to the datasource. | +|**dataSourceTypeName** |The data source type; see all possible values here . | +|**contentTypes** |Types of content in the data source, as defined by OpenDOAR. | +|**relOrganizationId** |Retrieve data sources connected to the organization (with OpenAIRE id). | +|**relCommunityId** |Retrieve data sources connected to the community (with OpenAIRE id). | +|**relCollectedFromDatasourceId**|Retrieve data sources collected from the data source (with OpenAIRE id). | +|**debugQuery** |Retrieve debug information for the search query. | +|**page** |Page number of the results. | +|**pageSize** |Number of results per page. | +|**sortBy** |The field to set the sorting order of the results. Should be provided in the format `Fieldname ASC\|DESC` - data sources can be only sorted by the `relevance`.| + + +### Projects + +The following query parameters are available for projects: + +| **Parameter** | **Description** | +|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|**search** | Search in the content of the projects. | +|**title** |Search in the project's title. | +|**keywords** |The project's keywords. | +|**id** |The OpenAIRE id of the project. | +|**code** |The grant agreement (GA) code of the project. | +|**acronym** |Project's acronym. | +|**callIdentifier** |The identifier of the research call. | +|**fundingShortName** |The short name of the funder. | +|**fundingStreamId** |The identifier of the funding stream. | +|**fromStartDate** |Gets the projects with start date greater than or equal to the given date. Please provide a date formatted as `YYYY-MM-DD`. | +|**toStartDate** |Gets the projects with start date less than or equal to the given date. Please provide a date formatted as `YYYY-MM-DD`. | +|**fromEndDate** |Gets the projects with end date greater than or equal to the given date. Please provide a date formatted as `YYYY-MM-DD`. | +|**toEndDate** |Gets the projects with end date less than or equal to the given date. Please provide a date formatted as `YYYY-MM-DD`. | +|**relOrganizationName** |The name or short name of the related organization. | +|**relOrganizationId** |The organization identifier of the related organization. | +|**relCommunityId** |Retrieve projects connected to the community (with OpenAIRE id). | +|**relOrganizationCountryCode** |The country code of the related organizations. | +|**relCollectedFromDatasourceId**|Retrieve projects collected from the data source (with OpenAIRE id). | +|**debugQuery** |Retrieve debug information for the search query. | +|**page** |Page number of the results. | +|**pageSize** |Number of results per page. | +|**sortBy** |The field to set the sorting order of the results. Should be provided in the format `fieldname ASC\|DESC`, where fieldname is one of `relevance`, `startDate`, `endDate`. Multiple sorting parameters should be comma-separated.| + + +## Using logical operators + +The API supports the use of logical operators `AND`, `OR`, and `NOT` to refine your search queries. +These operators help you combine or exclude one or more values for a specific filter. + + +### `AND` operator + +Use the `AND` operator to retrieve results that include all specified values. This narrows your search. + +Examples: + +- Get research products that contain both "climate" and "change": + + [https://openaire-api.athenarc.gr/researchProducts?search=climate AND change](https://openaire-api.athenarc.gr/researchProducts?search=climate%20AND%20change) + +- Get research products that are classified with both Fields of Study (FOS) "03 medical and health sciences" and "0502 economics and business": + + [https://openaire-api.athenarc.gr/researchProducts?fos="03 medical and health sciences" AND "0502 economics and business"](https://openaire-api.athenarc.gr/researchProducts?fos=%2203%20medical%20and%20health%20sciences%22%20AND%20%220502%20economics%20and%20business%22) + +### `OR` operator + +Use the `OR` operator to retrieve results that include any of the specified terms. This broadens your search. +The same functionality can be achieved by providing multiple times the same query parameter or using a comma to separate the values. + +Examples: + +- Get research products with the OpenAIRE ids `doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108` or `pmid_dedup__::1591ebf0e0698ed4a99455ff2ba4adc0`: + + [https://openaire-api.athenarc.gr/researchProducts?id=r3730f562f9e::539da48b3796663b17e6166bb966e5b1 OR pmid_dedup__::1591ebf0e0698ed4a99455ff2ba4adc0](https://openaire-api.athenarc.gr/researchProducts?id=r3730f562f9e::539da48b3796663b17e6166bb966e5b1%20OR%20pmid_dedup__::1591ebf0e0698ed4a99455ff2ba4adc0) + +- Get projects that are connected to organizations in the US or Greece: + + [https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US OR GR](https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US%20OR%20GR) + + or by using the same query parameter multiple times: [https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US&relOrganizationCountryCode=GR](https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US&relOrganizationCountryCode=GR) + + or just using comma: [https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US,GR](https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US,GR) + +### `NOT` operator + +Use the `NOT` operator to exclude specific terms from your search results. This refines your search by filtering out unwanted results. + +Examples: + +- Get research products that contain "semantic" but not "web": + + [https://openaire-api.athenarc.gr/researchProducts?search=semantic NOT web](https://openaire-api.athenarc.gr/researchProducts?search=semantic%20NOT%20web) + +- Get all data sources that are not journals: + + [https://openaire-api.athenarc.gr/dataSources?dataSourceTypeName=NOT Journal](https://openaire-api.athenarc.gr/dataSources?dataSourceTypeName=NOT%20Journal) + + +:::note +All the above operators can be combined, along with parentheses, and quotes to create more complex queries. +For example, to get research products that contain the phrase "semantic web" but not "ontology" or "linked data": + +[https://openaire-api.athenarc.gr/researchProducts?search="semantic web" AND NOT (ontology OR "linked data")](https://openaire-api.athenarc.gr/researchProducts?search=%22semantic%20web%22%20AND%20NOT%20(ontology%20OR%20%22linked%20data%22)) ::: \ No newline at end of file diff --git a/docs/apis/graph-api/search-entities/overview.md b/docs/apis/graph-api/search-entities/overview.md index 280762b..4595ef2 100644 --- a/docs/apis/graph-api/search-entities/overview.md +++ b/docs/apis/graph-api/search-entities/overview.md @@ -1,5 +1,44 @@ # Search entities -:::info warning -To be completed soon, for the next beta release. -::: \ No newline at end of file +This is a guide on how to search for specific entities using the OpenAIRE Graph API. + +## Endpoints + +Currently, the Graph API supports the following entity types: +* Research products - endpoint: [`GET /researchProducts`](https://openaire-api.athenarc.gr/researchProducts) +* Organizations - endpoint: [`GET /organizations`](https://openaire-api.athenarc.gr/organizations) +* Data sources - endpoint: [`GET /dataSources`](https://openaire-api.athenarc.gr/dataSources) +* Projects - endpoint: [`GET /projects`](https://openaire-api.athenarc.gr/projects) + +Each of these endpoints can be used to list all entities of the corresponding type. +Listing such entities can be more useful when using the [filtering](./filter-search-results), +[sorting](./sorting-and-paging.md#sorting), and [pagination](./sorting-and-paging.md#paging) capabilities of the Graph API. + +## Response + +The response of the aforementioned endpoints is an object of the following type: + +```json +{ + header: { + numFound: 36818386, + maxScore: 1, + queryTime: 21, + page: 1, + pageSize: 10 + }, + results: [ + ... + ] +} + +``` + +It contains a `header` object with the following fields: +- `numFound`: the total number of entities found +- `maxScore`: the maximum relevance score of the search results +- `queryTime`: the time in milliseconds that the search took +- `page`: the current page of the search results +- `pageSize`: the number of entities per page + +Finally, the `results` field contains an array of entities of the corresponding type (i.e., [Research product](../../../data-model/entities/research-product), [Organization](../../../data-model/entities/organization), [Data Source](../../../data-model/entities/data-source), or [Project](../../../data-model/entities/project)). diff --git a/docs/apis/graph-api/search-entities/pagination.md b/docs/apis/graph-api/search-entities/pagination.md deleted file mode 100644 index 8c0c46f..0000000 --- a/docs/apis/graph-api/search-entities/pagination.md +++ /dev/null @@ -1,5 +0,0 @@ -# Pagination - -:::info warning -To be completed soon, for the next beta release. -::: \ No newline at end of file diff --git a/docs/apis/graph-api/search-entities/sort-search-results.md b/docs/apis/graph-api/search-entities/sort-search-results.md deleted file mode 100644 index e0346a9..0000000 --- a/docs/apis/graph-api/search-entities/sort-search-results.md +++ /dev/null @@ -1,5 +0,0 @@ -# Sort search results - -:::info warning -To be completed soon, for the next beta release. -::: \ No newline at end of file diff --git a/docs/apis/graph-api/search-entities/sorting-and-paging.md b/docs/apis/graph-api/search-entities/sorting-and-paging.md new file mode 100644 index 0000000..44f735d --- /dev/null +++ b/docs/apis/graph-api/search-entities/sorting-and-paging.md @@ -0,0 +1,46 @@ +# Sorting and paging + +The OpenAIRE Graph API allows you to sort and page through the results of your search queries. +This enables you to retrieve the most relevant results and manage large result sets more effectively. + +# Sorting +Sorting based on specific fields, helps to retrieve data in the preferred order. +Sorting is achieved using the `sortBy` parameter, which specifies the field and the direction (ascending or descending) for sorting. + +* `sortBy`: Defines the field and the sort direction. The format should be `fieldname sortDirection`, where the `sortDirection` can be either `ASC` for ascending order or `DESC` for descending order. + +The field names that can be used for sorting are specific to each entity type and can be found in the `sortBy` field values of the [available paremeters](../search-entities/filter-search-results#available-parameters). + +Note that the default sorting is based on the `relevance` score of the search results. + +Examples: + +- Get research products published after 2020-01-01 and sort them by the publication date in descending order: + + [https://openaire-api.athenarc.gr/researchProducts?fromPublicationDate=2020-01-01&sortBy=publicationDate DESC](https://openaire-api.athenarc.gr/researchProducts?fromPublicationDate=2020-01-01&sortBy=publicationDate%20DESC) + +- Get research products with the keyword "COVID-19" and sort them by their (citation-based) popularity: + + [https://openaire-api.athenarc.gr/researchProducts?search=COVID-19&sortBy=popularity DESC](https://openaire-api.athenarc.gr/researchProducts?search=COVID-19&sortBy=popularity%20DESC) + +Note that you can combine multiple sorting conditions by separating them with a comma. + +Example: + +- Get research products with the keyword "COVID-19" and sort them by their publication date in ascending order and then by their popularity in descending order: + + [https://openaire-api.athenarc.gr/researchProducts?search=COVID-19&sortBy=publicationDate ASC,popularity DESC](https://openaire-api.athenarc.gr/researchProducts?search=COVID-19&sortBy=publicationDate%20ASC,popularity%20DESC) + +# Paging + +The OpenAIRE Graph API supports paging through the use of `page` and `pageSize` parameters, enabling you to specify which part of the result set to retrieve and how many results per page. + +* `page`: Specifies the page number of the results you want to retrieve. Page numbering starts from 1. + +* `pageSize`: Defines the number of results to be returned per page. This helps limit the amount of data returned in a single request, making it easier to process. + +Example: + +- Get the top 10 most influential research products that contain the phrase "knowledge graphs": + + [https://openaire-api.athenarc.gr/researchProducts?search="knowledge graphs"&page=1&pageSize=10&sortBy=influence DESC](https://openaire-api.athenarc.gr/researchProducts?search=%22knowledge%20graphs%22&page=1&pageSize=10&sortBy=influence%20DESC) \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index a195bf5..94a8f65 100644 --- a/sidebars.js +++ b/sidebars.js @@ -70,10 +70,10 @@ const sidebars = { link: { type: 'doc', id: 'apis/graph-api/search-entities/overview' }, items: [ { type: 'doc', id: 'apis/graph-api/search-entities/filter-search-results' }, - { type: 'doc', id: 'apis/graph-api/search-entities/sort-search-results' }, - { type: 'doc', id: 'apis/graph-api/search-entities/pagination' }, + { type: 'doc', id: 'apis/graph-api/search-entities/sorting-and-paging' }, ] - } + }, + { type: 'doc', id: 'apis/graph-api/making-requests' }, ] }, { From 1b641d86abed620e73253bad65362e5923025731 Mon Sep 17 00:00:00 2001 From: Serafeim Chatzopoulos Date: Thu, 11 Jul 2024 19:56:14 +0300 Subject: [PATCH 5/7] Change urls to point to the api-beta && add making requests page --- docs/apis/graph-api/get-single-entities.md | 53 ------------------- .../apis/graph-api/getting-a-single-entity.md | 50 +++++++++++++++++ docs/apis/graph-api/making-requests.md | 36 ++++++++----- docs/apis/graph-api/overview.md | 17 +++--- .../filtering-search-results.md} | 39 +++++++------- .../overview.md | 14 ++--- .../sorting-and-paging.md | 20 +++---- sidebars.js | 10 ++-- 8 files changed, 124 insertions(+), 115 deletions(-) delete mode 100644 docs/apis/graph-api/get-single-entities.md create mode 100644 docs/apis/graph-api/getting-a-single-entity.md rename docs/apis/graph-api/{search-entities/filter-search-results.md => searching-entities/filtering-search-results.md} (90%) rename docs/apis/graph-api/{search-entities => searching-entities}/overview.md (72%) rename docs/apis/graph-api/{search-entities => searching-entities}/sorting-and-paging.md (52%) diff --git a/docs/apis/graph-api/get-single-entities.md b/docs/apis/graph-api/get-single-entities.md deleted file mode 100644 index 0d82b41..0000000 --- a/docs/apis/graph-api/get-single-entities.md +++ /dev/null @@ -1,53 +0,0 @@ -# Get single entities - -This is a guide on how to retrieve detailed information on a single entity using the OpenAIRE Graph API. - -## Endpoints -Currently, the Graph API supports the following entity types: - -- Research products - endpoint: `GET /researchProducts/{id}` -- Organizations - endpoint: `GET /organizations/{id}` -- Data sources - endpoint: `GET /dataSources/{id}` -- Projects - endpoint: `GET /projects/{id}` - -You can retrieve the data of a single entity by providing the entity's OpenAIRE identifier (id) in the corresponding endpoint. -The OpenAIRE id is the primary key of an entity in the OpenAIRE Graph. - -:::note -Note that if you want to retrieve multiple entities based on their OpenAIRE ids, you can use the [search endpoints and filter](./search-entities/filter-search-results#or-operator) by the `id` field using `OR`. -::: - -## Response -The response of the Graph API is a [Research product](../../data-model/entities/research-product), [Organization](../../data-model/entities/organization), [Data Source](../../data-model/entities/data-source), or [Project](../../data-model/entities/project), depending on the endpoint used. - -## Example - -In order to retrieve the research product with OpenAIRE id: `doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108`, -you have to perform the following API call: - -[https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108](https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108) - -This will return all the data of the research product with the provided identifier: - -```json -{ - "id": "doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108", - "mainTitle": "Political conservatism as motivated social cognition.", - "description": [ - "Analyzing political conservatism as motivated social cognition integrates theories of personality (authoritarianism, dogmatism-intolerance of ambiguity), epistemic and existential needs (for closure, regulatory focus, terror management), and ideological rationalization (social dominance, system justification). A meta-analysis (88 samples, 12 countries, 22,818 cases) confirms that several psychological variables predict political conservatism: death anxiety (weighted mean r = .50); system instability (.47); dogmatism-intolerance of ambiguity (.34); openness to experience (-.32); uncertainty tolerance (-.27); needs for order, structure, and closure (.26); integrative complexity (-.20); fear of threat and loss (.18); and self-esteem (-.09). The core ideology of conservatism stresses resistance to change and justification of inequality and is motivated by needs that vary situationally and dispositionally to manage uncertainty and threat." - ], - "type": "publication", - "publicationDate": "2003-01-01", - "publisher": "American Psychological Association (APA)", - "source": [ - "Crossref" - ], - "pid": [ - { - "scheme": "Digital Object Identifier", - "value": "10.1037/0033-2909.129.3.339" - } - ], - // for brevity, the rest of the fields are omitted -} -``` \ No newline at end of file diff --git a/docs/apis/graph-api/getting-a-single-entity.md b/docs/apis/graph-api/getting-a-single-entity.md new file mode 100644 index 0000000..c0e977f --- /dev/null +++ b/docs/apis/graph-api/getting-a-single-entity.md @@ -0,0 +1,50 @@ +# Getting a single entity + +This is a guide on how to retrieve detailed information on a single entity using the OpenAIRE Graph API. + +## Endpoints +Currently, the Graph API supports the following entity types: + +- Research products - endpoint: `GET /researchProducts/{id}` +- Organizations - endpoint: `GET /organizations/{id}` +- Data sources - endpoint: `GET /dataSources/{id}` +- Projects - endpoint: `GET /projects/{id}` + +You can retrieve the data of a single entity by providing the entity's OpenAIRE identifier (id) in the corresponding endpoint. +The OpenAIRE id is the primary key of an entity in the OpenAIRE Graph. + +:::note +Note that if you want to retrieve multiple entities based on their OpenAIRE ids, you can use the [search endpoints and filter](./searching-entities/filtering-search-results#or-operator) by the `id` field using `OR`. +::: + +## Response +The response of the Graph API is a [Research product](../../data-model/entities/research-product), [Organization](../../data-model/entities/organization), [Data Source](../../data-model/entities/data-source), or [Project](../../data-model/entities/project), depending on the endpoint used. + +## Example + +In order to retrieve the research product with OpenAIRE id: `doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108`, +you have to perform the following API call: + +[https://api-beta.openaire.eu/graph/researchProducts/doi_dedup___::a55b42c0d32a4a24cf99e621623d110e](https://api-beta.openaire.eu/graph/researchProducts/doi_dedup___::a55b42c0d32a4a24cf99e621623d110e) + +This will return all the data of the research product with the provided identifier: + +```json +{ + id: "doi_dedup___::a55b42c0d32a4a24cf99e621623d110e", + mainTitle: "OpenAIRE Graph Dataset", + description: [ + "The OpenAIRE Graph is exported as several dataseta, so you can download the parts you are interested into. publication_[part].tar: metadata records about research literature (includes types of publications listed here)
dataset_[part].tar: metadata records about research data (includes the subtypes listed here)
software.tar: metadata records about research software (includes the subtypes listed here)
otherresearchproduct_[part].tar: metadata records about research products that cannot be classified as research literature, data or software (includes types of products listed here)
organization.tar: metadata records about organizations involved in the research life-cycle, such as universities, research organizations, funders.
datasource.tar: metadata records about data sources whose content is available in the OpenAIRE Graph. They include institutional and thematic repositories, journals, aggregators, funders' databases.
project.tar: metadata records about project grants.
relation_[part].tar: metadata records about relations between entities in the graph.
communities_infrastructures.tar: metadata records about research communities and research infrastructures Each file is a tar archive containing gz files, each with one json per line. Each json is compliant to the schema available at http://doi.org/10.5281/zenodo.8238874. The documentation for the model is available at https://graph.openaire.eu/docs/data-model/ Learn more about the OpenAIRE Graph at https://graph.openaire.eu. Discover the graph's content on OpenAIRE EXPLORE and our API for developers." + ], + type: "dataset", + publicationDate: "2023-08-08", + publisher: "Zenodo", + id: [ + { + scheme: "Digital Object Identifier", + value: "10.5281/zenodo.8217359" + } + ], + // for brevity, the rest of the fields are omitted +} +``` \ No newline at end of file diff --git a/docs/apis/graph-api/making-requests.md b/docs/apis/graph-api/making-requests.md index 3df7c0d..7f1be3c 100644 --- a/docs/apis/graph-api/making-requests.md +++ b/docs/apis/graph-api/making-requests.md @@ -1,33 +1,41 @@ # Making requests -or using code: +This guide provides examples of how to make requests to the OpenAIRE Graph API using different programming languages. - - - +## Using `curl` ```bash -curl -X GET "https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108" -H "accept: application/json" +curl -X GET "https://api-beta.openaire.eu/graph/researchProducts?search=OpenAIRE%20Graph&type=publication&page=1&pageSize=10&sortBy=relevance%20DESC" -H "accept: application/json" ``` - - + +## Using Python (with `requests` library) ```python import requests -url = "https://openaire-api.athenarc.gr/researchProducts/doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108" +url = "https://api-beta.openaire.eu/graph/researchProducts" +params = { + "search": "OpenAIRE Graph", + "type": "publication", + "page": 1, + "pageSize": 10, + "sortBy": "relevance DESC" +} headers = { "accept": "application/json" } -response = requests.get(url, headers=headers) +response = requests.get(url, headers=headers, params=params) if response.status_code == 200: - print(response.json()) + data = response.json() + print(data) else: - print(f"Request failed with status code {response.status_code}") -``` - + print(f"Failed to retrieve data: {response.status_code}") - \ No newline at end of file +``` + +:::note +Note that when using `curl` you should ensure that the URL is properly encoded, especially when using special characters or spaces in the query parameters. On the contrary, the `requests` library in Python takes care of URL encoding automatically. +::: \ No newline at end of file diff --git a/docs/apis/graph-api/overview.md b/docs/apis/graph-api/overview.md index a9f8031..79b90b9 100644 --- a/docs/apis/graph-api/overview.md +++ b/docs/apis/graph-api/overview.md @@ -1,4 +1,5 @@ -# Graph API +# Graph API beta + The OpenAIRE Graph API provides a comprehensive way for developers to explore the [OpenAIRE Graph](https://graph.openaire.eu/), a vast interconnected dataset that aggregates metadata from a wide range of scholarly resources. The Graph API offers endpoints for accessing and querying this interconnected dataset, enabling users to retrieve detailed information on research products, data sources, organizations, and projects. @@ -7,10 +8,10 @@ The Graph API offers endpoints for accessing and querying this interconnected da The base URL of the Graph API is: ``` -https://openaire-api.athenarc.gr/ +https://api-beta.openaire.eu/graph/ ``` -You can access the API Swagger documentation in [https://openaire-api.athenarc.gr/swagger-ui/index.html#/](https://openaire-api.athenarc.gr/swagger-ui/index.html#/). +You can access the API Swagger documentation in [https://api-beta.openaire.eu/graph/swagger-ui/index.html#/](https://api-beta.openaire.eu/graph/swagger-ui/index.html#/). ## Notes Please note that the Graph API: @@ -22,9 +23,9 @@ Please note that the Graph API: Please use the following links to learn more about the Graph API: -- [Get single entities](./get-single-entities) - Retrieve detailed information on a single entity. -- [Search entities](./search-entities/overview) - Retrieve a list of entities based on specific search criteria. - - [Filter search results](./search-entities/filter-search-results) - Filter search results based on specific criteria. - - [Sort search results](./search-entities/sorting-and-paging#sorting) - Sort search results based on specific criteria. - - [Pagination](./search-entities/sorting-and-paging#paging) - Retrieve a subset of search results. +- [Getting a single entity](./getting-a-single-entity) - Retrieve detailed information on a single entity. +- [Searching entities](./searching-entities/overview) - Retrieve a list of entities based on specific search criteria. + - [Filtering results](./searching-entities/filtering-search-results) - Filter search results based on specific criteria. + - [Sorting results](./searching-entities/sorting-and-paging#sorting) - Sort search results based on specific criteria. + - [Paging](./searching-entities/sorting-and-paging#paging) - Retrieve a subset of search results. - [Making requests](./making-requests) - Learn how to make requests with different programming languages. diff --git a/docs/apis/graph-api/search-entities/filter-search-results.md b/docs/apis/graph-api/searching-entities/filtering-search-results.md similarity index 90% rename from docs/apis/graph-api/search-entities/filter-search-results.md rename to docs/apis/graph-api/searching-entities/filtering-search-results.md index 877bba0..2cc09ea 100644 --- a/docs/apis/graph-api/search-entities/filter-search-results.md +++ b/docs/apis/graph-api/searching-entities/filtering-search-results.md @@ -1,4 +1,4 @@ -# Filter search results +# Filtering search results Filters can be used to narrow down the search results based on specific criteria. Filters are provided as query parameters in the request URL (see [here](./overview#endpoints) for the available search entpoints). @@ -14,17 +14,17 @@ For more information on how to use logical operators when searching and filterin Examples: -- Get all research products that contain the word "covid", sorted by popularity in descending order: +- Get all research products that contain the word `"covid"`, sorted by popularity in descending order: - [https://openaire-api.athenarc.gr/researchProducts?search=covid&sortBy=popularity DESC](https://openaire-api.athenarc.gr/researchProducts?search=covid&sortBy=popularity%20DESC) + [https://api-beta.openaire.eu/graph/researchProducts?search=covid&sortBy=popularity DESC](https://api-beta.openaire.eu/graph/researchProducts?search=covid&sortBy=popularity%20DESC) -- Get all publications that are published after 2019-01-01: +- Get all publications that are published after `2019-01-01`: - [https://openaire-api.athenarc.gr/researchProducts?type=publication&fromPublicationDate=2019-01-01](https://openaire-api.athenarc.gr//researchProducts?type=publication&fromPublicationDate=2019-01-01) + [https://api-beta.openaire.eu/graph/researchProducts?type=publication&fromPublicationDate=2019-01-01](https://api-beta.openaire.eu/graph/researchProducts?type=publication&fromPublicationDate=2019-01-01) - Get the organization with the ROR id `https://ror.org/0576by029`: - [https://openaire-api.athenarc.gr/organizations?pid=https://ror.org/0576by029](https://openaire-api.athenarc.gr/organizations?pid=https://ror.org/0576by029) + [https://api-beta.openaire.eu/graph/organizations?pid=https://ror.org/0576by029](https://api-beta.openaire.eu/graph/organizations?pid=https://ror.org/0576by029) ## Available parameters @@ -165,14 +165,17 @@ Use the `AND` operator to retrieve results that include all specified values. Th Examples: -- Get research products that contain both "climate" and "change": +- Get research products that contain both `"climate"` and `"change"`: - [https://openaire-api.athenarc.gr/researchProducts?search=climate AND change](https://openaire-api.athenarc.gr/researchProducts?search=climate%20AND%20change) + [https://api-beta.openaire.eu/graph/researchProducts?search=climate AND change](https://api-beta.openaire.eu/graph/researchProducts?search=climate%20AND%20change) -- Get research products that are classified with both Fields of Study (FOS) "03 medical and health sciences" and "0502 economics and business": +- Get research products that are classified with both Fields of Study (FOS) `"03 medical and health sciences"` and `"0502 economics and business"`: - [https://openaire-api.athenarc.gr/researchProducts?fos="03 medical and health sciences" AND "0502 economics and business"](https://openaire-api.athenarc.gr/researchProducts?fos=%2203%20medical%20and%20health%20sciences%22%20AND%20%220502%20economics%20and%20business%22) + [https://api-beta.openaire.eu/graph/researchProducts?fos="03 medical and health sciences" AND "0502 economics and business"](https://api-beta.openaire.eu/graph/researchProducts?fos=%2203%20medical%20and%20health%20sciences%22%20AND%20%220502%20economics%20and%20business%22) +:::note +Note that when multiple tokens denote a single filter value, you should enclose them in double quotes, as in the FOS example above. +::: ### `OR` operator Use the `OR` operator to retrieve results that include any of the specified terms. This broadens your search. @@ -182,15 +185,15 @@ Examples: - Get research products with the OpenAIRE ids `doi_dedup___::2b3cb7130c506d1c3a05e9160b2c4108` or `pmid_dedup__::1591ebf0e0698ed4a99455ff2ba4adc0`: - [https://openaire-api.athenarc.gr/researchProducts?id=r3730f562f9e::539da48b3796663b17e6166bb966e5b1 OR pmid_dedup__::1591ebf0e0698ed4a99455ff2ba4adc0](https://openaire-api.athenarc.gr/researchProducts?id=r3730f562f9e::539da48b3796663b17e6166bb966e5b1%20OR%20pmid_dedup__::1591ebf0e0698ed4a99455ff2ba4adc0) + [https://api-beta.openaire.eu/graph/researchProducts?id=r3730f562f9e::539da48b3796663b17e6166bb966e5b1 OR pmid_dedup__::1591ebf0e0698ed4a99455ff2ba4adc0](https://api-beta.openaire.eu/graph/researchProducts?id=r3730f562f9e::539da48b3796663b17e6166bb966e5b1%20OR%20pmid_dedup__::1591ebf0e0698ed4a99455ff2ba4adc0) - Get projects that are connected to organizations in the US or Greece: - [https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US OR GR](https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US%20OR%20GR) + [https://api-beta.openaire.eu/graph/projects?relOrganizationCountryCode=US OR GR](https://api-beta.openaire.eu/graph/projects?relOrganizationCountryCode=US%20OR%20GR) - or by using the same query parameter multiple times: [https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US&relOrganizationCountryCode=GR](https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US&relOrganizationCountryCode=GR) + or by using the same query parameter multiple times: [https://api-beta.openaire.eu/graph/projects?relOrganizationCountryCode=US&relOrganizationCountryCode=GR](https://api-beta.openaire.eu/graph/projects?relOrganizationCountryCode=US&relOrganizationCountryCode=GR) - or just using comma: [https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US,GR](https://openaire-api.athenarc.gr/projects?relOrganizationCountryCode=US,GR) + or just using comma: [https://api-beta.openaire.eu/graph/projects?relOrganizationCountryCode=US,GR](https://api-beta.openaire.eu/graph/projects?relOrganizationCountryCode=US,GR) ### `NOT` operator @@ -198,18 +201,18 @@ Use the `NOT` operator to exclude specific terms from your search results. This Examples: -- Get research products that contain "semantic" but not "web": +- Get research products that contain `"semantic"` but not `"web"`: - [https://openaire-api.athenarc.gr/researchProducts?search=semantic NOT web](https://openaire-api.athenarc.gr/researchProducts?search=semantic%20NOT%20web) + [https://api-beta.openaire.eu/graph/researchProducts?search=semantic NOT web](https://api-beta.openaire.eu/graph/researchProducts?search=semantic%20NOT%20web) - Get all data sources that are not journals: - [https://openaire-api.athenarc.gr/dataSources?dataSourceTypeName=NOT Journal](https://openaire-api.athenarc.gr/dataSources?dataSourceTypeName=NOT%20Journal) + [https://api-beta.openaire.eu/graph/dataSources?dataSourceTypeName=NOT Journal](https://api-beta.openaire.eu/graph/dataSources?dataSourceTypeName=NOT%20Journal) :::note All the above operators can be combined, along with parentheses, and quotes to create more complex queries. For example, to get research products that contain the phrase "semantic web" but not "ontology" or "linked data": -[https://openaire-api.athenarc.gr/researchProducts?search="semantic web" AND NOT (ontology OR "linked data")](https://openaire-api.athenarc.gr/researchProducts?search=%22semantic%20web%22%20AND%20NOT%20(ontology%20OR%20%22linked%20data%22)) +[https://api-beta.openaire.eu/graph/researchProducts?search="semantic web" AND NOT (ontology OR "linked data")](https://api-beta.openaire.eu/graph/researchProducts?search=%22semantic%20web%22%20AND%20NOT%20(ontology%20OR%20%22linked%20data%22)) ::: \ No newline at end of file diff --git a/docs/apis/graph-api/search-entities/overview.md b/docs/apis/graph-api/searching-entities/overview.md similarity index 72% rename from docs/apis/graph-api/search-entities/overview.md rename to docs/apis/graph-api/searching-entities/overview.md index 4595ef2..ce59be5 100644 --- a/docs/apis/graph-api/search-entities/overview.md +++ b/docs/apis/graph-api/searching-entities/overview.md @@ -1,18 +1,18 @@ -# Search entities +# Searching entities This is a guide on how to search for specific entities using the OpenAIRE Graph API. ## Endpoints Currently, the Graph API supports the following entity types: -* Research products - endpoint: [`GET /researchProducts`](https://openaire-api.athenarc.gr/researchProducts) -* Organizations - endpoint: [`GET /organizations`](https://openaire-api.athenarc.gr/organizations) -* Data sources - endpoint: [`GET /dataSources`](https://openaire-api.athenarc.gr/dataSources) -* Projects - endpoint: [`GET /projects`](https://openaire-api.athenarc.gr/projects) +* Research products - endpoint: [`GET /researchProducts`](https://api-beta.openaire.eu/graph/researchProducts) +* Organizations - endpoint: [`GET /organizations`](https://api-beta.openaire.eu/graph/organizations) +* Data sources - endpoint: [`GET /dataSources`](https://api-beta.openaire.eu/graph/dataSources) +* Projects - endpoint: [`GET /projects`](https://api-beta.openaire.eu/graph/projects) Each of these endpoints can be used to list all entities of the corresponding type. -Listing such entities can be more useful when using the [filtering](./filter-search-results), -[sorting](./sorting-and-paging.md#sorting), and [pagination](./sorting-and-paging.md#paging) capabilities of the Graph API. +Listing such entities can be more useful when using the [filtering](./filtering-search-results), +[sorting](./sorting-and-paging#sorting), and [paging](./sorting-and-paging#paging) capabilities of the Graph API. ## Response diff --git a/docs/apis/graph-api/search-entities/sorting-and-paging.md b/docs/apis/graph-api/searching-entities/sorting-and-paging.md similarity index 52% rename from docs/apis/graph-api/search-entities/sorting-and-paging.md rename to docs/apis/graph-api/searching-entities/sorting-and-paging.md index 44f735d..3458a3c 100644 --- a/docs/apis/graph-api/search-entities/sorting-and-paging.md +++ b/docs/apis/graph-api/searching-entities/sorting-and-paging.md @@ -3,35 +3,35 @@ The OpenAIRE Graph API allows you to sort and page through the results of your search queries. This enables you to retrieve the most relevant results and manage large result sets more effectively. -# Sorting +## Sorting Sorting based on specific fields, helps to retrieve data in the preferred order. Sorting is achieved using the `sortBy` parameter, which specifies the field and the direction (ascending or descending) for sorting. * `sortBy`: Defines the field and the sort direction. The format should be `fieldname sortDirection`, where the `sortDirection` can be either `ASC` for ascending order or `DESC` for descending order. -The field names that can be used for sorting are specific to each entity type and can be found in the `sortBy` field values of the [available paremeters](../search-entities/filter-search-results#available-parameters). +The field names that can be used for sorting are specific to each entity type and can be found in the `sortBy` field values of the [available paremeters](../searching-entities/filtering-search-results#available-parameters). Note that the default sorting is based on the `relevance` score of the search results. Examples: -- Get research products published after 2020-01-01 and sort them by the publication date in descending order: +- Get research products published after `2020-01-01` and sort them by the publication date in descending order: - [https://openaire-api.athenarc.gr/researchProducts?fromPublicationDate=2020-01-01&sortBy=publicationDate DESC](https://openaire-api.athenarc.gr/researchProducts?fromPublicationDate=2020-01-01&sortBy=publicationDate%20DESC) + [https://api-beta.openaire.eu/graph/researchProducts?fromPublicationDate=2020-01-01&sortBy=publicationDate DESC](https://api-beta.openaire.eu/graph/researchProducts?fromPublicationDate=2020-01-01&sortBy=publicationDate%20DESC) -- Get research products with the keyword "COVID-19" and sort them by their (citation-based) popularity: +- Get research products with the keyword `"COVID-19"` and sort them by their (citation-based) popularity: - [https://openaire-api.athenarc.gr/researchProducts?search=COVID-19&sortBy=popularity DESC](https://openaire-api.athenarc.gr/researchProducts?search=COVID-19&sortBy=popularity%20DESC) + [https://api-beta.openaire.eu/graph/researchProducts?search=COVID-19&sortBy=popularity DESC](https://api-beta.openaire.eu/graph/researchProducts?search=COVID-19&sortBy=popularity%20DESC) Note that you can combine multiple sorting conditions by separating them with a comma. Example: -- Get research products with the keyword "COVID-19" and sort them by their publication date in ascending order and then by their popularity in descending order: +- Get research products with the keyword `"COVID-19"` and sort them by their publication date in ascending order and then by their popularity in descending order: - [https://openaire-api.athenarc.gr/researchProducts?search=COVID-19&sortBy=publicationDate ASC,popularity DESC](https://openaire-api.athenarc.gr/researchProducts?search=COVID-19&sortBy=publicationDate%20ASC,popularity%20DESC) + [https://api-beta.openaire.eu/graph/researchProducts?search=COVID-19&sortBy=publicationDate ASC,popularity DESC](https://api-beta.openaire.eu/graph/researchProducts?search=COVID-19&sortBy=publicationDate%20ASC,popularity%20DESC) -# Paging +## Paging The OpenAIRE Graph API supports paging through the use of `page` and `pageSize` parameters, enabling you to specify which part of the result set to retrieve and how many results per page. @@ -43,4 +43,4 @@ Example: - Get the top 10 most influential research products that contain the phrase "knowledge graphs": - [https://openaire-api.athenarc.gr/researchProducts?search="knowledge graphs"&page=1&pageSize=10&sortBy=influence DESC](https://openaire-api.athenarc.gr/researchProducts?search=%22knowledge%20graphs%22&page=1&pageSize=10&sortBy=influence%20DESC) \ No newline at end of file + [https://api-beta.openaire.eu/graph/researchProducts?search="knowledge graphs"&page=1&pageSize=10&sortBy=influence DESC](https://api-beta.openaire.eu/graph/researchProducts?search=%22knowledge%20graphs%22&page=1&pageSize=10&sortBy=influence%20DESC) \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 94a8f65..ca88c55 100644 --- a/sidebars.js +++ b/sidebars.js @@ -63,14 +63,14 @@ const sidebars = { label: "Graph API", link: { type: 'doc', id: 'apis/graph-api/overview' }, items: [ - { type: 'doc', id: 'apis/graph-api/get-single-entities' }, + { type: 'doc', id: 'apis/graph-api/getting-a-single-entity' }, { type: 'category', - label: "Search entities", - link: { type: 'doc', id: 'apis/graph-api/search-entities/overview' }, + label: "Searching entities", + link: { type: 'doc', id: 'apis/graph-api/searching-entities/overview' }, items: [ - { type: 'doc', id: 'apis/graph-api/search-entities/filter-search-results' }, - { type: 'doc', id: 'apis/graph-api/search-entities/sorting-and-paging' }, + { type: 'doc', id: 'apis/graph-api/searching-entities/filtering-search-results' }, + { type: 'doc', id: 'apis/graph-api/searching-entities/sorting-and-paging' }, ] }, { type: 'doc', id: 'apis/graph-api/making-requests' }, From 1d75eb9d9a724fedd71c031c1ea7d7c378456992 Mon Sep 17 00:00:00 2001 From: Serafeim Chatzopoulos Date: Thu, 11 Jul 2024 20:05:57 +0300 Subject: [PATCH 6/7] Fix sorting direction --- .../searching-entities/filtering-search-results.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/apis/graph-api/searching-entities/filtering-search-results.md b/docs/apis/graph-api/searching-entities/filtering-search-results.md index 2cc09ea..a2ce7a2 100644 --- a/docs/apis/graph-api/searching-entities/filtering-search-results.md +++ b/docs/apis/graph-api/searching-entities/filtering-search-results.md @@ -76,7 +76,7 @@ The following query parameters are available for research products: | **debugQuery** | Retrieve debug information for the search query. (Boolean) | | **page** | Page number of the results. (Integer) | | **pageSize** | Number of results per page. Integer in the range [1, 100] | -| **sortBy** | The field to set the sorting order of the results. Should be provided in the format `fieldname ASC\|DESC`, where fieldname is one of `relevance`, `publicationDate`, `dateOfCollection`, `influence`, `popularity`, `citationCount`, `impulse`. Multiple sorting parameters should be comma-separated. | +| **sortBy** | The field to set the sorting order of the results. Should be provided in the format `fieldname sortDirection`, where the `sortDirection` can be either `ASC` for ascending order or `DESC` for descending order and `fielaname` is one of `relevance`, `publicationDate`, `dateOfCollection`, `influence`, `popularity`, `citationCount`, `impulse`. Multiple sorting parameters should be comma-separated. | ### Organizations @@ -96,7 +96,7 @@ The following query parameters are available for organizations: |**debugQuery** |Retrieve debug information for the search query. | |**page** |Page number of the results. | |**pageSize** |Number of results per page. | -|**sortBy** |The field to set the sorting order of the results. Should be provided in the format `fieldname ASC\|DESC` - organizations can be only sorted by the `relevance`.| +|**sortBy** |The field to set the sorting order of the results. Should be provided in the format `fieldname sortDirection`, where the `sortDirection` can be either `ASC` for ascending order or `DESC` for descending order - organizations can only be sorted by `relevance`.| ### Data sources @@ -120,7 +120,7 @@ The following query parameters are available for data sources: |**debugQuery** |Retrieve debug information for the search query. | |**page** |Page number of the results. | |**pageSize** |Number of results per page. | -|**sortBy** |The field to set the sorting order of the results. Should be provided in the format `Fieldname ASC\|DESC` - data sources can be only sorted by the `relevance`.| +|**sortBy** |The field to set the sorting order of the results. Should be provided in the format `fieldname sortDirection`, where the `sortDirection` can be either `ASC` for ascending order or `DESC` for descending order - data sources can only be sorted by `relevance`.| ### Projects @@ -150,7 +150,7 @@ The following query parameters are available for projects: |**debugQuery** |Retrieve debug information for the search query. | |**page** |Page number of the results. | |**pageSize** |Number of results per page. | -|**sortBy** |The field to set the sorting order of the results. Should be provided in the format `fieldname ASC\|DESC`, where fieldname is one of `relevance`, `startDate`, `endDate`. Multiple sorting parameters should be comma-separated.| +|**sortBy** |The field to set the sorting order of the results. Should be provided in the format `fieldname sortDirection`, where the `sortDirection` can be either `ASC` for ascending order or `DESC` for descending order and `fielaname` is one of `relevance`, `startDate`, `endDate`. Multiple sorting parameters should be comma-separated.| ## Using logical operators From 02dcb2d950540302570df45d320e4745eb5958fb Mon Sep 17 00:00:00 2001 From: Serafeim Chatzopoulos Date: Fri, 12 Jul 2024 17:21:11 +0300 Subject: [PATCH 7/7] Fix broken links --- docs/apis/graph-api/getting-a-single-entity.md | 4 ++-- docs/apis/graph-api/{overview.md => graph-api.md} | 14 +++++++------- .../searching-entities/filtering-search-results.md | 2 +- .../{overview.md => searching-entities.md} | 6 +++--- .../searching-entities/sorting-and-paging.md | 2 +- docs/apis/home.md | 2 +- sidebars.js | 4 ++-- 7 files changed, 17 insertions(+), 17 deletions(-) rename docs/apis/graph-api/{overview.md => graph-api.md} (64%) rename docs/apis/graph-api/searching-entities/{overview.md => searching-entities.md} (79%) diff --git a/docs/apis/graph-api/getting-a-single-entity.md b/docs/apis/graph-api/getting-a-single-entity.md index c0e977f..432bb68 100644 --- a/docs/apis/graph-api/getting-a-single-entity.md +++ b/docs/apis/graph-api/getting-a-single-entity.md @@ -14,11 +14,11 @@ You can retrieve the data of a single entity by providing the entity's OpenAIRE The OpenAIRE id is the primary key of an entity in the OpenAIRE Graph. :::note -Note that if you want to retrieve multiple entities based on their OpenAIRE ids, you can use the [search endpoints and filter](./searching-entities/filtering-search-results#or-operator) by the `id` field using `OR`. +Note that if you want to retrieve multiple entities based on their OpenAIRE ids, you can use the [search endpoints and filter](./searching-entities/filtering-search-results.md#or-operator) by the `id` field using `OR`. ::: ## Response -The response of the Graph API is a [Research product](../../data-model/entities/research-product), [Organization](../../data-model/entities/organization), [Data Source](../../data-model/entities/data-source), or [Project](../../data-model/entities/project), depending on the endpoint used. +The response of the Graph API is a [Research product](../../data-model/entities/research-product.md), [Organization](../../data-model/entities/organization.md), [Data Source](../../data-model/entities/data-source.md), or [Project](../../data-model/entities/project.md), depending on the endpoint used. ## Example diff --git a/docs/apis/graph-api/overview.md b/docs/apis/graph-api/graph-api.md similarity index 64% rename from docs/apis/graph-api/overview.md rename to docs/apis/graph-api/graph-api.md index 79b90b9..f26f8bb 100644 --- a/docs/apis/graph-api/overview.md +++ b/docs/apis/graph-api/graph-api.md @@ -16,16 +16,16 @@ You can access the API Swagger documentation in [https://api-beta.openaire.eu/gr ## Notes Please note that the Graph API: -- is intended for data discovery and exploration; if you are interested in downloading the full OpenAIRE Graph dataset, please navigate [here](../../downloads/full-graph). +- is intended for data discovery and exploration; if you are interested in downloading the full OpenAIRE Graph dataset, please navigate [here](../../downloads/full-graph.md). - adhers to the [terms of use](../terms.md) of the OpenAIRE public APIs - certain (rate limit) restrictions apply. ## Learn more Please use the following links to learn more about the Graph API: -- [Getting a single entity](./getting-a-single-entity) - Retrieve detailed information on a single entity. -- [Searching entities](./searching-entities/overview) - Retrieve a list of entities based on specific search criteria. - - [Filtering results](./searching-entities/filtering-search-results) - Filter search results based on specific criteria. - - [Sorting results](./searching-entities/sorting-and-paging#sorting) - Sort search results based on specific criteria. - - [Paging](./searching-entities/sorting-and-paging#paging) - Retrieve a subset of search results. -- [Making requests](./making-requests) - Learn how to make requests with different programming languages. +- [Getting a single entity](./getting-a-single-entity.md) - Retrieve detailed information on a single entity. +- [Searching entities](./searching-entities/searching-entities.md) - Retrieve a list of entities based on specific search criteria. + - [Filtering results](./searching-entities/filtering-search-results.md) - Filter search results based on specific criteria. + - [Sorting results](./searching-entities/sorting-and-paging.md#sorting) - Sort search results based on specific criteria. + - [Paging](./searching-entities/sorting-and-paging.md#paging) - Retrieve a subset of search results. +- [Making requests](./making-requests.md) - Learn how to make requests with different programming languages. diff --git a/docs/apis/graph-api/searching-entities/filtering-search-results.md b/docs/apis/graph-api/searching-entities/filtering-search-results.md index a2ce7a2..b8e239f 100644 --- a/docs/apis/graph-api/searching-entities/filtering-search-results.md +++ b/docs/apis/graph-api/searching-entities/filtering-search-results.md @@ -1,7 +1,7 @@ # Filtering search results Filters can be used to narrow down the search results based on specific criteria. -Filters are provided as query parameters in the request URL (see [here](./overview#endpoints) for the available search entpoints). +Filters are provided as query parameters in the request URL (see [here](./searching-entities.md) for the available search entpoints). Multiple filters can be provided in a single request; they should be formatted as follows: `param1=value1¶m2=value2&...¶mN=valueN`. diff --git a/docs/apis/graph-api/searching-entities/overview.md b/docs/apis/graph-api/searching-entities/searching-entities.md similarity index 79% rename from docs/apis/graph-api/searching-entities/overview.md rename to docs/apis/graph-api/searching-entities/searching-entities.md index ce59be5..57f5e10 100644 --- a/docs/apis/graph-api/searching-entities/overview.md +++ b/docs/apis/graph-api/searching-entities/searching-entities.md @@ -11,8 +11,8 @@ Currently, the Graph API supports the following entity types: * Projects - endpoint: [`GET /projects`](https://api-beta.openaire.eu/graph/projects) Each of these endpoints can be used to list all entities of the corresponding type. -Listing such entities can be more useful when using the [filtering](./filtering-search-results), -[sorting](./sorting-and-paging#sorting), and [paging](./sorting-and-paging#paging) capabilities of the Graph API. +Listing such entities can be more useful when using the [filtering](./filtering-search-results.md), +[sorting](./sorting-and-paging.md#sorting), and [paging](./sorting-and-paging.md#paging) capabilities of the Graph API. ## Response @@ -41,4 +41,4 @@ It contains a `header` object with the following fields: - `page`: the current page of the search results - `pageSize`: the number of entities per page -Finally, the `results` field contains an array of entities of the corresponding type (i.e., [Research product](../../../data-model/entities/research-product), [Organization](../../../data-model/entities/organization), [Data Source](../../../data-model/entities/data-source), or [Project](../../../data-model/entities/project)). +Finally, the `results` field contains an array of entities of the corresponding type (i.e., [Research product](../../../data-model/entities/research-product.md), [Organization](../../../data-model/entities/organization.md), [Data Source](../../../data-model/entities/data-source.md), or [Project](../../../data-model/entities/project.md)). diff --git a/docs/apis/graph-api/searching-entities/sorting-and-paging.md b/docs/apis/graph-api/searching-entities/sorting-and-paging.md index 3458a3c..ff88a26 100644 --- a/docs/apis/graph-api/searching-entities/sorting-and-paging.md +++ b/docs/apis/graph-api/searching-entities/sorting-and-paging.md @@ -9,7 +9,7 @@ Sorting is achieved using the `sortBy` parameter, which specifies the field and * `sortBy`: Defines the field and the sort direction. The format should be `fieldname sortDirection`, where the `sortDirection` can be either `ASC` for ascending order or `DESC` for descending order. -The field names that can be used for sorting are specific to each entity type and can be found in the `sortBy` field values of the [available paremeters](../searching-entities/filtering-search-results#available-parameters). +The field names that can be used for sorting are specific to each entity type and can be found in the `sortBy` field values of the [available paremeters](../searching-entities/filtering-search-results.md#available-parameters). Note that the default sorting is based on the `relevance` score of the search results. diff --git a/docs/apis/home.md b/docs/apis/home.md index aa25e6e..24198f2 100644 --- a/docs/apis/home.md +++ b/docs/apis/home.md @@ -1,7 +1,7 @@ # Public APIs The OpenAIRE Graph data are accessible through various public APIs. More specifically, the following APIs are currently provided: -* [Graph API](./graph-api/overview) - an API to explore the OpenAIRE Graph +* [Graph API](./graph-api/graph-api.md) - an API to explore the OpenAIRE Graph * [Search API](./search-api/search-api.md) - an API to search for research products and projects * [ScholeXplorer API](https://api.scholexplorer.openaire.eu/swagger-ui/index.html?urls.primaryName=Scholexplorer%20API%20V2.0) - an API offering dataset-publication & dataset-dataset links * [DSpace & EPrints API](./dspace-eprints-api.md) - an API to offer custom access to metadata for projects funded by a selection of international funders for DSpace and EPrints platforms diff --git a/sidebars.js b/sidebars.js index ca88c55..c7c317c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -61,13 +61,13 @@ const sidebars = { { type: 'category', label: "Graph API", - link: { type: 'doc', id: 'apis/graph-api/overview' }, + link: { type: 'doc', id: 'apis/graph-api/graph-api' }, items: [ { type: 'doc', id: 'apis/graph-api/getting-a-single-entity' }, { type: 'category', label: "Searching entities", - link: { type: 'doc', id: 'apis/graph-api/searching-entities/overview' }, + link: { type: 'doc', id: 'apis/graph-api/searching-entities/searching-entities' }, items: [ { type: 'doc', id: 'apis/graph-api/searching-entities/filtering-search-results' }, { type: 'doc', id: 'apis/graph-api/searching-entities/sorting-and-paging' },