Change urls to point to the api-beta && add making requests page

This commit is contained in:
Serafeim Chatzopoulos 2024-07-11 19:56:14 +03:00
parent 8b12f7bf04
commit 1b641d86ab
8 changed files with 124 additions and 115 deletions

View File

@ -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
}
```

View File

@ -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. <strong>publication_[part].tar</strong>: metadata records about research literature (includes types of publications listed here)<br> <strong>dataset_[part].tar</strong>: metadata records about research data (includes the subtypes listed here) <br> <strong>software.tar</strong>: metadata records about research software (includes the subtypes listed here)<br> <strong>otherresearchproduct_[part].tar</strong>: metadata records about research products that cannot be classified as research literature, data or software (includes types of products listed here)<br> <strong>organization.tar</strong>: metadata records about organizations involved in the research life-cycle, such as universities, research organizations, funders.<br> <strong>datasource.tar</strong>: metadata records about data sources whose content is available in the OpenAIRE Graph. They include institutional and thematic repositories, journals, aggregators, funders' databases.<br> <strong>project.tar</strong>: metadata records about project grants.<br> <strong>relation_[part].tar</strong>: metadata records about relations between entities in the graph.<br> <strong>communities_infrastructures.tar</strong>: 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
}
```

View File

@ -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.
<Tabs>
<TabItem value="research-product-curl" label="Curl">
## 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"
```
</TabItem>
<TabItem value="research-product-python" label="Python">
## 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}")
```
</TabItem>
print(f"Failed to retrieve data: {response.status_code}")
</Tabs>
```
:::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.
:::

View File

@ -1,4 +1,5 @@
# Graph API
# Graph API <span class="theme-doc-version-badge badge badge--secondary">beta</span>
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.

View File

@ -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))
:::

View File

@ -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

View File

@ -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)
[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)

View File

@ -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' },