From ca12a508bad53b93f19d5ed0e431689f448d828b Mon Sep 17 00:00:00 2001 From: Serafeim Chatzopoulos Date: Thu, 11 Jan 2024 18:05:41 +0200 Subject: [PATCH] Add Docs for APIs --- docs/api/api.md | 6 -- docs/{api => apis}/_category_.json | 0 docs/apis/authenticated-requests.md | 78 +++++++++++++++ docs/apis/broker-api.md | 50 ++++++++++ docs/apis/dspace-eprints-api.md | 61 ++++++++++++ docs/apis/home.md | 9 ++ docs/apis/search-api/projects.md | 31 ++++++ .../search-api/response-metadata-format.md | 20 ++++ docs/apis/search-api/results.md | 98 +++++++++++++++++++ docs/apis/search-api/search-api.md | 3 + docs/apis/specification-changelog.md | 93 ++++++++++++++++++ docs/apis/terms.md | 17 ++++ sidebars.js | 34 ++++++- static/resources/athenarc_fos_hierarchy.json | 1 + 14 files changed, 492 insertions(+), 9 deletions(-) delete mode 100644 docs/api/api.md rename docs/{api => apis}/_category_.json (100%) create mode 100644 docs/apis/authenticated-requests.md create mode 100644 docs/apis/broker-api.md create mode 100644 docs/apis/dspace-eprints-api.md create mode 100644 docs/apis/home.md create mode 100644 docs/apis/search-api/projects.md create mode 100644 docs/apis/search-api/response-metadata-format.md create mode 100644 docs/apis/search-api/results.md create mode 100644 docs/apis/search-api/search-api.md create mode 100644 docs/apis/specification-changelog.md create mode 100644 docs/apis/terms.md create mode 100644 static/resources/athenarc_fos_hierarchy.json diff --git a/docs/api/api.md b/docs/api/api.md deleted file mode 100644 index 1cf4b7f..0000000 --- a/docs/api/api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -sidebar_position: 5 ---- - -# Public API -TODO: https://graph.openaire.eu/develop/overview.html \ No newline at end of file diff --git a/docs/api/_category_.json b/docs/apis/_category_.json similarity index 100% rename from docs/api/_category_.json rename to docs/apis/_category_.json diff --git a/docs/apis/authenticated-requests.md b/docs/apis/authenticated-requests.md new file mode 100644 index 0000000..4186509 --- /dev/null +++ b/docs/apis/authenticated-requests.md @@ -0,0 +1,78 @@ +# Guide for authenticated requests + +The OpenAIRE APIs can be accessed over HTTPS both by authenticated and non authenticated requests. Currently, there is **an adjustment period until October 2022**, when the rate limit for both authenticated and non authenticated requests is up to 7200 requests per hour. **After this period we plan to significantly lower the rate limit of non authenticated requests up to 60 requests per hour.** + +Please consider to make authenticated requests to achieve better rate limits. Check our Privacy Policy [here](http://www.openaire.eu/privacy-policy). + +### OpenAIRE APIs - Rate limits + + + + + + + + + + +
Not authenticated requestsUp to 7200 requests per hour
soon to decrease - please see above
Authenticated requestsUp to 7200 request per hour
+ +OpenAIRE APIs can be used for both authentication and authorization. Our OAuth 2.0 implementation, conforms to the OpenID Connect specification, and is [OpenID Certified](https://openid.net/certification/). OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. For more information about OAuth2.0 please visit the [OAuth2.0 official site](https://oauth.net/2/). For more information about OpenID Connect please visit the [OpenID Connect official site](https://openid.net/connect/). + +## Requests + +To access the OpenAIRE APIs with better rate limits, send your access token using the Authorization header. + +```js +GET https://api.openaire.eu/{resourceServicePath} +Authorization: Bearer {ACCESS_TOKEN} +``` + + + +## Response Headers + +| Name | D | +| --- | --- | +| x-ratelimit-limit | The maximum number of requests allowed for the client in one time window. | +| x-ratelimit-used | The number of requests already made by the client in the current time window. | + +The OpenAIRE APIs use a sliding time window of one hour. + +## Error Messages + +404 - Not found + +```json +{ + "error": "Not found", + "description": "Invald request path." +} +``` + +403 - Invalid Access Token + +```json +{ + "error": "Token invalid", + "description": "Authorization header value invalid." +} +``` + +429 - Rate limit abuse for unauthenticated user + +```json +{ + "error": "Too many requests", + "description": "Request rate exceeded. Slow down." +} +``` + +429 - Rate limit abuse + +```json +{ + "error": "Too many requests", + "description": "Request rate exceeded. Slow down." +} +``` \ No newline at end of file diff --git a/docs/apis/broker-api.md b/docs/apis/broker-api.md new file mode 100644 index 0000000..7e6e6fb --- /dev/null +++ b/docs/apis/broker-api.md @@ -0,0 +1,50 @@ +# Broker API + + +## Introduction + +The Broker Service is available to use via the OpenAIRE Content Provider Dashboard. Thanks to the Broker, repositories, publishers or aggregators can exchange metadata and enrich their local metadata collection by subscribing to notifications of different types. The Broker is able to notify providers when the OpenAIRE Graph contains information that is not available in the original collection of the data source. In particular, the data source manager can subscribe via the [Content Provider Dashboard](https://provide.openaire.eu) and be notified about: + +* Additional PIDs of its publications (e.g. DOIs) +* Links to projects +* ORCID that can be associated to an author of datasource publications +* Links to Open Access versions +* Additional classification subjects (e.g. subjects from standard schemes like ACM, JEL and DDC) +* Abstracts identified in duplicate publications +* Missing publication dates + +All Repository managers approaching the Content Provider Dashboard will be offered the possibility to preview a set of enrichments relative to their repository that OpenAIRE can derive from the Graph. More specifically, enrichments will be organized into categories named topics and representing the different types of enrichments OpenAIRE can build. For each topic the preview consists of 100 “enrichment events”, a subset of all the possible enrichments pertinent to a given repository in the OpenAIRE Graph, that the user can explore by applying filters on different criteria and the total number of events that can be potentially built is highlighted in the UI. Repository managers can create subscriptions for specific topics and that include the filtering criteria they used to analyze the enrichments preview, or can subscribe to all the available topics with no restrictions at once. Once the repository manager creates a subscription, the algorithm analyzing the OpenAIRE Graph will produce the full set of enrichments for the manager's repository, possibly far beyond the 100 enrichments available in the preview. The enrichments will be made available as notifications in a dedicated section in the Content Provider Dashboard UI to be further checked as well as through the broker service API for programmatic access. Notifications will be sent to subscribers every time the OpenAIRE Graph will be updated and analyzed to derive the enrichments. + +## Usage Example + +The following commands indicate how the broker API documented at [api.openaire.eu/broker](https://api.openaire.eu/broker/swagger-ui/index.html) can be used to access the set of enrichments: + +1. Get the list of subscriptions for a given subscriber, e.g. + + ```js + curl -X GET --header 'Accept: application/json' 'https://api.openaire.eu/broker/subscriptions?email=[subscriber_email]' + ``` + +2. Extract the subscription ID and use it to access the 1st page of enrichment notification records + + ```js + curl -X GET --header 'Accept: application/json' 'https://api.openaire.eu/broker/scroll/notifications/bySubscriptionId/[sub-1234]' + ``` + +3. Extract the scroll ID from the response to request subsequent pages + + ```js + curl -X GET --header 'Accept: application/json' 'https://api.openaire.eu/broker/scroll/notifications/[scroll_id]' + ``` + +To simplify accessing the enrichment notification records, please check the OpenAIRE broker cmdline client available on [GitHub](https://github.com/openaire/broker-cmdline-client). + +## Terms of Use and SLA + +APIs are free-to-use (no sign-up needed) by any third-party service + +**Metadata license is CC-BY**: the metadata records retuned by the service can be freely re-used by commercial and non-commercial partners under CC-BY license, hence as long as OpenAIRE is acknowledged as data source. + +**Quality of Service**: all API services are running in production 24/7 within the OpenAIRE infrastructure premises deployed at the [data center](http://icm.edu.pl/en/centre-of-technology/) facilities of the [Interdisciplinary Centre for Mathematical and Computational Modelling](http://icm.edu.pl/en/) (ICM). + +**APIs rate limits**: please check [here](./authenticated-requests). \ No newline at end of file diff --git a/docs/apis/dspace-eprints-api.md b/docs/apis/dspace-eprints-api.md new file mode 100644 index 0000000..b02391b --- /dev/null +++ b/docs/apis/dspace-eprints-api.md @@ -0,0 +1,61 @@ +# Dspace & EPrints API + + +The APIs offer custom access to metadata about projects funded by a selection of international funders for the **DSpace** and **EPrints** platforms. The currently supported funders and relative codes are: + +* **FP7:** The 7th Framework Programme funded by the European Commission +* **H2020:** Horizon2020 Programme funded by the European Commission +* **HE:** Horizon Europe Programme funded by the European Commission +* **AKA:** Academy of Finland +* **ARC:** Australian Research Council +* **FWF:** Austrian Science Foundation +* **CHISTERA:** CHIST-ERA +* **CIHR:** Canadian Institutes of Health Research +* **HRZZ:** Croatian Science Foundation +* **EEA:** European Environemnt Agency +* **ANR:** French National Research Agency +* **FCT:** The funding programme of Fundação para a Ciência e a Tecnologia, the national funding agency of Portugal +* **MESTD:** The Ministry of Education, Science and Technological Development of Serbia +* **MZOS:** Ministry of Science, Education and Sports of the Republic of Croatia +* **NHMRC:** Australian National Health and Medical Research Council +* **NIH:** US National Institutes of Health +* **NSF:** US National Science Foundation +* **NSERC:** Natural Sciences and Engineering Research Council of Canada +* **NWO:** The Netherlands Organisation for Scientific Research +* **SFI:** Science Foundation Ireland +* **SSHRC:** Social Sciences and Humanities Research Council +* **SNSF:** Swiss National Science Foundation +* **TARA:** Tara Expeditions Foundation +* **TUBITAK:** The National funder of Turkey +* **UKRI:** United Kingdom Research and Innovation +* **WT:** Wellcome Trust + +## DSpace/ePrints + +DSpace endpoint: http://api.openaire.eu/projects/dspace/$fundingStream/ALL/ALL + +ePrints endpoint: http://api.openaire.eu/projects/eprints/$fundingStream/ALL/ALL + +The URLs embed the parameters needed to collect projects funded by specific funding stream, where the pattern is FundingStream/FundingSubStream/FundingSubSubStream. +Additional parameters can be concatenated to the URL to refine the results by date (date must be in the form `YYYY-MM-DD`): + +* startFrom +* startUntil +* endFrom +* endUntil + +## Examples + +Get Wellcome Trust projects for EPrints: [http://api.openaire.eu/projects/eprints/WT/ALL/ALL](http://api.openaire.eu/projects/eprints/WT/ALL/ALL) +Get EC-FP7 projects of the specific programme “SP2-IDEAS” for EPrints: [http://api.openaire.eu/projects/eprints/FP7/SP2/ALL](http://api.openaire.eu/projects/eprints/FP7/SP2/ALL) +Get EC-FP7 projects for DSpace that started after the given date: [http://api.openaire.eu/projects/dspace/FP7/ALL/ALL?startFrom=2011-01-01](http://api.openaire.eu/projects/dspace/FP7/ALL/ALL?startFrom=2011-01-01). + +## Terms of Use and SLA + +APIs are free-to-use (no sign-up needed) by any third-party service. + +**Metadata license is CC-BY**: the metadata records retuned by the service can be freely re-used by commercial and non-commercial partners under CC-BY license, hence as long as OpenAIRE is acknowledged as data source. + +**Quality of Service**: all API services are running in production 24/7 within the OpenAIRE infrastructure premises deployed at the [data center](http://icm.edu.pl/en/centre-of-technology/) facilities of the [Interdisciplinary Centre for Mathematical and Computational Modelling](http://icm.edu.pl/en/) (ICM). + +**APIs rate limits**: please check [here](./authenticated-requests). \ No newline at end of file diff --git a/docs/apis/home.md b/docs/apis/home.md new file mode 100644 index 0000000..d443526 --- /dev/null +++ b/docs/apis/home.md @@ -0,0 +1,9 @@ +# Public APIs + +The OpenAIRE Graph data are accessible through various public APIs. More specifically, the following APIs are currently provided: +* Search API (an API to search for research results and projects) +* ScholeXplorer API (an API offering dataset-publication & dataset-dataset links) +* DSpace & EPrints API (an API to offer custom access to metadata for projects funded by a selection of international funders for DSpace and EPrints platforms) +* Broker API (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/docs/apis/search-api/projects.md b/docs/apis/search-api/projects.md new file mode 100644 index 0000000..686debf --- /dev/null +++ b/docs/apis/search-api/projects.md @@ -0,0 +1,31 @@ +# Searching for projects + +## Endpoints + +For research projects: http://api.openaire.eu/search/projects + +## Parameters + +| Parameter | Option | Description | +| --- | --- | --- | +| page | integer | Page number of the search results. | +| size | integer | Number of results per page. | +| format | json \| xml \| csv \| tsv | The format of the response. The default is xml. | +| model | openaire \| sygma | The data model of the response. Default is openaire. Model sygma is a simplified version of the openaire model. For sygma, only the xml format is available. The relative XML schema is available [here](https://www.openaire.eu/schema/sygma/oaf_sygma_v2.1.xsd). | +| sortBy | `sortBy=field,[ascending\|descending]`; **'field'** is one of: `projectstartdate`, `projectstartyear`, `projectenddate`, `projectendyear`, `projectduration` | The sorting order of the specified field. | +| hasECFunding | true \| false | If hasECFunding is true gets the entities funded by the EC. If hasECFunding is false gets the entities related to projects not funded by the EC. | +| hasWTFunding | true \| false | If hasWTFunding is true gets the entities funded by Wellcome Trust. The results are the same as those obtained with `funder=wt`. If hasWTFunding is false gets the entities related to projects not funded by Wellcome Trust. | +| funder | WT \| EC \| ARC \| ANDS \| NSF \| FCT \| NHMRC | Search for entities by funder. | +| fundingStream | ... | Search for entities by funding stream. | +| FP7scientificArea | ... | Search for FP7 entities by scientific area. | +| keywords | White-space separated list of keywords. | N/A | +| sortBy | `sortBy=field,[ascending\|descending]`; **'field'** is one of: `projectstartdate`, `projectstartyear`, `projectenddate`, `projectendyear`, `projectduration` | The sorting order of the specified field. | +| grantID | Comma separated list of grant identifiers. | Gets the project with the given grant identifier, if any. | +| openairePublicationID | Comma separated list of OpenAIRE identifiers. | Gets the publication with the given openaire identifier, if any. | +| name | White-space separated list of keywords. | Gets the projects whose names contain the given list of keywords. Using double quotes `"` you get an exact match, if any. | +| acronym | N/A | Gets the project with the given acronym, if any. | +| callID | N/A | Search for projects by call identifier. | +| startYear | Year formatted as `YYYY` | Gets the projects that started in the given year. | +| endYear | Year formatted as `YYYY`. | Gets the projects that ended in the given year. | +| participantCountries | Comma separeted list of 2 letter country codes. | Search for projects by participant countries. | +| participantAcronyms | White space separeted list of acronyms of institutions. | Search for projects by participant institutions. | \ No newline at end of file diff --git a/docs/apis/search-api/response-metadata-format.md b/docs/apis/search-api/response-metadata-format.md new file mode 100644 index 0000000..444df24 --- /dev/null +++ b/docs/apis/search-api/response-metadata-format.md @@ -0,0 +1,20 @@ +# Response metadata format + + +The default format of delivered records is oaf (OpenAIRE Format - current version 1.0): + +* XML schema: https://www.openaire.eu/schema/1.0/oaf-1.0.xsd +* Documentation: https://www.openaire.eu/schema/1.0/doc/oaf-1.0.html + +For the list of changes [click here](https://www.openaire.eu/openaire-xml-schema-change-announcement). + +Note that latest versions of the XML schema and documentation are also available at the following permanent links: + +* XML schema: https://www.openaire.eu/schema/latest/oaf.xsd +* Documentation: https://www.openaire.eu/schema/latest/doc/oaf.html + +Older versions: + +* oaf v0.3 [XML schema](https://www.openaire.eu/schema/0.3/oaf-0.3.xsd) and [documentation](https://www.openaire.eu/schema/0.3/doc/oaf-0.3.html) +* oaf v0.2 [XML schema](https://www.openaire.eu/schema/0.2/oaf-0.2.xsd) and [documentation](https://www.openaire.eu/schema/0.2/doc/oaf-0.2.html) +* oaf v0.1 [XML schema](https://www.openaire.eu/schema/0.1/oaf-0.1.xsd) and [documentation](https://www.openaire.eu/schema/0.1/doc/oaf-0.1.html) \ No newline at end of file diff --git a/docs/apis/search-api/results.md b/docs/apis/search-api/results.md new file mode 100644 index 0000000..b77dbe1 --- /dev/null +++ b/docs/apis/search-api/results.md @@ -0,0 +1,98 @@ +# Searching for research results + +## Endpoints + +For research products: https://api.openaire.eu/search/researchProducts + +By specific type: +* publications: https://api.openaire.eu/search/publications +* research data: https://api.openaire.eu/search/datasets +* research software: https://api.openaire.eu/search/software +* other research products: http://api.openaire.eu/search/other + + +## General parameters + +Endpoint: https://api.openaire.eu/search/researchProducts + +| Parameter | Option | Description | +| --- | --- | --- | +| page | integer | Page number of the search results. | +| size | integer | Number of results per page. | +| format | json \| xml \| csv \| tsv | The format of the response. The default is xml. | +| model | openaire \| sygma | The data model of the response. Default is openaire. Model sygma is a simplified version of the openaire model. For sygma, only the xml format is available. The relative XML schema is available [here](https://www.openaire.eu/schema/sygma/oaf_sygma_v2.1.xsd). | +| sortBy | `sortBy=field,[ascending\|descending]`; **'field'** is one of: `dateofcollection`,`resultstoragedate`,`resultstoragedate`, `resultembargoenddate`,`resultembargoendyear`,`resultdateofacceptance`, `resultacceptanceyear`,`influence`,`popularity`, `citationCount`,`impulse`
Multiple sorting is supported by repeating the `sortBy` parameter. | The sorting order of the specified field. | +| hasECFunding | true \| false | If hasECFunding is true gets the entities funded by the EC. If hasECFunding is false gets the entities related to projects not funded by the EC. | +| hasWTFunding | true \| false | If hasWTFunding is true gets the entities funded by Wellcome Trust. The results are the same as those obtained with `funder=wt`. If hasWTFunding is false gets the entities related to projects not funded by Wellcome Trust. | +| funder | WT \| EC \| ARC \| ANDS \| NSF \| FCT \| NHMRC | Search for entities by funder. | +| fundingStream | ... | Search for entities by funding stream. | +| FP7scientificArea | ... | Search for FP7 entities by scientific area. | +| keywords | White-space separated list of keywords. | N/A | +| doi | Comma separated list of DOIs.
Alternatively, it is possible to repeat the parameter for each requested doi. | Gets the research products with the given DOIs, if any. | +| orcid | Comma separated list of ORCID iDs of authors.
Alternatively, it is possible to repeat the parameter for each author ORCID iD. | Gets the research products linked to the given ORCID iD of an author, if any. | +| fromDateAccepted | Date formatted as `YYYY-MM-DD` | Gets the research products whose date of acceptance is greater than or equal the given date. | +| toDateAccepted | Date formatted as `YYYY-MM-DD` | Gets the research products whose date of acceptance is less than or equal the given date. | +| title | White-space separated list of keywords. | Gets the research products whose titles contain the given list of keywords. | +| author | White-space separated list of names and/or surnames. | Search for research products by authors. | +| OA | true \| false | If OA is true gets Open Access research products. If OA is false gets the non Open Access research products | +| projectID | The given grant identifier of the project | Search for research products of the project with the specified projectID | +| country | 2 letter country code | Search for research products associated to the country code | +| influence
| Accepted values:
`C1` for top 0.01% in terms of influence
`C2` for top 0.1% in terms of influence
`C3` for top 1% in terms of influence
`C4` for top 10% in terms of influence
`C5` for average/low in terms of influence

Comma separated list of values or repeat of the parameter for each value will form a query with OR semantics, eg. `?influence=C1&influence=C2` | Search for research products based on their influence. | +| popularity
| Accepted values:
`C1` for top 0.01% in terms of popularity
`C2` for top 0.1% in terms of popularity
`C3` for top 1% in terms of popularity
`C4` for top 10% in terms of popularity
`C5` for average/low in terms of popularity

Comma separated list of values or repeat of the parameter for each value will form a query with OR semantics, eg. `?popularity=C1&popularity=C2` | Search for research products based on their popularity. | +| impulse
| Accepted values:
`C1` for top 0.01% in terms of impulse
`C2` for top 0.1% in terms of impulse
`C3` for top 1% in terms of impulse
`C4` for top 10% in terms of impulse
`C5` for average/low in terms of impulse

Comma separated list of values or repeat of the parameter for each value will form a query with OR semantics, eg. `?impulse=C1&impulse=C2` | Search for research products based on their impulse. | +| citationCount
| Accepted values:
`C1` for top 0.01% in terms of citation count
`C2` for top 0.1% in terms of citation count
`C3` for top 1% in terms of citation count
`C4` for top 10% in terms of citation count
`C5` for average/low in terms of citation count

Comma separated list of values or repeat of the parameter for each value will form a query with OR semantics, eg. `?citationCount=C1&citationCount=C2` | Search for research products based on their number of citations. | +| openaireProviderID | Comma separated list of identifiers. | Search for research products by openaire data provider identifier.
Alternatively, it is possible to repeat the parameter for each provider id. In both cases, provider identifiers will form a query with OR semantics. | +| openaireProjectID | Comma separated list of identifiers.
Alternatively, it is possible to repeat the parameter for each provider id. In both cases, provider identifiers will form a query with OR semantics. | Search for research products by openaire project identifier. Alternatively, it is possible to repeat the parameter for each provider id. In both cases, provider identifiers will form a query with OR semantics. | +| hasProject | true \| false | If hasProject is true gets the research products that have a link to a project. If hasProject is false gets the publications with no links to projects. | +| FP7ProjectID | ... | Search for research products associated to a FP7 project with the given grant number. It is equivalent to a query by `funder=FP7&projectID={grantID}` | + + +## Parameters for publications + +Endpoint: https://api.openaire.eu/search/publications + +You can use all the [general research products parameters](#general-parameters) as well as those in the following table. + +| Parameter | Option | Description | +| --- | --- | --- | +| instancetype | Comma separated list of publication types. Check [here](http://api.openaire.eu/vocabularies/dnet:publication_resource) to see the possible values | Gets the publication of the given type, if any. | +| originalId | Comma separated list of original identifiers as we get them from the data source.
Alternatively, it is possible to repeat the parameter for each requested identifier. | Gets the publication with the given openaire identifier, if any. | +| sdg | The number of the Sustainable Development Goals `[1-17]`.
Check [here](https://sdgs.un.org/goals) to see the Sustainable Developemnt Goals. | Gets the publications that are classified with the respective Sustainable Development Goal number. | +| fos | The Field of Science classification value.
Check [here](/resources/athenarc_fos_hierarchy.json) to see the Field of Science classification values | Gets the publications that are classified with the respective Field of Science classification value. | +| openairePublicationID | Comma separated list of OpenAIRE identifiers.
Alternatively, it is possible to repeat the parameter for each requested identifier. | Gets the publication with the given openaire identifier, if any. | +| peerReviewed | Accepted values:
true \| false | Specify if the publications are peerReviewed or not. | +| diamondJournal | Accepted values:
true \| false | Specify if the publications are published in a diamond journal or not. | +| publiclyFunded | Accepted values:
true \| false | Specify if the publications are publicly funded or not. | +| green | Accepted values:
true \| false | Specify if the publications are green open access or not. | +| openAccessColor | Accepted values:
`gold`\| `bronze`\| `hybrid`
Comma separated list of values or repeat of the parameter for each value will form a query with OR semantics, eg. `?openAccessColor=gold&openAccessColor=hybrid` | Specify the open access color of a publication. | + +## Parameters for research data + +Endpoint: https://api.openaire.eu/search/datasets + +You can use all the [general research products parameters](#general-parameters) as well as those in the following table. + +| Parameter | Option | Description | +| --- | --- | --- | +| openaireDatasetID | Comma separated list of OpenAIRE identifiers.
Alternatively, it is possible to repeat the parameter for each requested identifier. | Gets the research data with the given openaire identifier, if any. | + +## Parameters for research software + +Endpoint: https://api.openaire.eu/search/software + +You can use all the [general research products parameters](#general-parameters) as well as those in the following table. + +| Parameter | Option | Description | +| --- | --- | --- | +| openaireSoftwareID | Comma separated list of OpenAIRE identifiers.
Alternatively, it is possible to repeat the parameter for each requested identifier. | Gets the research software with the given openaire identifier, if any. | + +## Parameters for other research products + +Endpoint: https://api.openaire.eu/search/other + +You can use all the [general research products parameters](#general-parameters) as well as those in the following table. + +| Parameter | Option | Description | +| --- | --- | --- | +| openaireOtherID | Comma separated list of OpenAIRE identifiers.
Alternatively, it is possible to repeat the parameter for each requested identifier. | Gets the other research products with the given openaire identifier, if any. | + diff --git a/docs/apis/search-api/search-api.md b/docs/apis/search-api/search-api.md new file mode 100644 index 0000000..e42758a --- /dev/null +++ b/docs/apis/search-api/search-api.md @@ -0,0 +1,3 @@ +# Search API + +The Search API allows developers to access metadata records of the OpenAIRE Graph by performing queries over research results (i.e., publications, data, software, other research products), and projects. The API is intended for metadata discovery and exploration only, hence it does not provide access to the whole information space: the number of total results returned by one query is limited to 10,000. For accessing the whole graph, developers are encouraged to use the [OpenAIRE full Graph dataset](../../downloads/full-graph). diff --git a/docs/apis/specification-changelog.md b/docs/apis/specification-changelog.md new file mode 100644 index 0000000..1b1d6f9 --- /dev/null +++ b/docs/apis/specification-changelog.md @@ -0,0 +1,93 @@ +# APIs specification changelog + +| Date | Description | +| --- | --- | +| 2024-01-09T11:14:10.524604Z | New parameters for publications. Now you can specifυ if they are peer reviewed, in diamond journal, publicly funded, green and specify their OA colour. | +| 2023-11-30T11:39:10.159187Z | Added impact factor parameters. Now you can sort results and query by impact, influence, impulse and citation count. | +| 2023-11-29T12:26:17.660379Z | New registration and token process available at https://develop.openaire.eu. Updated documentation | +| 2023-05-25T09:16:19.903365Z | new instancetype parameter added | +| 2022-09-29T07:03:32.109909Z | updated URLs to the broker swagger UI | +| 2022-09-28T20:35:13.116653Z | updated URLs to the broker swagger UI | +| 2022-07-28T12:02:06.271154Z | Updated list of funders supported by the API for bulk access to projects: EC Horizon Europe also included | +| 2022-05-11T10:01:33.969973Z | New end point for researchProducts in selective access! FOS and SDG classifications available for publication requests | +| 2022-03-29T15:03:29.583536Z | Graph dumps: add new Scholix version 4 | +| 2021-11-12T12:04:52.900385Z | originalId parameter added | +| 2021-10-18T15:31:18.446582Z | OAI-PMH publisher completely dismissed as announced in January 2021 | +| 2021-10-12T07:46:48.032978Z | orcid parameter added in selective access | +| 2021-04-08T10:28:02.371361Z | Authenticated requests to our APIs are now enabled. | +| 2021-02-26T16:28:15.364435Z | NEWS: new dump available with research products with project funding information | +| 2021-02-17T07:39:46.051129Z | WIP: broker API documentation | +| 2021-02-11T09:06:41.608115Z | Broker API documentation | +| 2021-02-10T10:17:39.504429Z | Authentication documentation added + broker card + broker dummy page | +| 2021-02-01T08:55:35.496938Z | OAI-PMH shutdown announced for the end of April 2021 | +| 2021-01-15T18:56:04.748404Z | Updated documentation on OpenAIRE Research Graph dumps | +| 2021-01-15T16:57:08.569766Z | Announcing the shutdown of the OAI-PMH publisher | +| 2019-01-25T15:36:27.264313Z | Added new parameter country for research results | +| 2018-10-17T10:39:56.570815Z | Software and Other research products are available via HTTP API. Documentation has been updated. | +| 2018-04-09T09:20:24.763966Z | Added section on terms of services and SLA in the specific API pages | +| 2018-04-09T08:26:18.897089Z | Added section for terms of use and SLA in the home page | +| 2018-03-21T15:31:13.490821Z | dded page with list of changes generated from the svn log | +| 2018-03-21T14:58:14.569096Z | Added APi rate limits | +| 2018-03-21T14:46:32.362617Z | ignore intellij settings | +| 2018-02-01T14:44:00.743257Z | Latest schema version is 1.0 | +| 2018-01-30T10:29:03.037760Z | removed authorOpenaireId parameter + change the message to say the schema is already changed | +| 2018-01-26T13:09:17.887663Z | Removed openaireAuthorID from API documentation | +| 2018-01-11T14:41:29.910148Z | Rephrase LOD to Linked Open Data | +| 2018-01-11T13:56:40.051318Z | add LOD box in overview.html | +| 2018-01-11T13:48:19.812005Z | Adding warning for schema change | +| 2017-10-23T14:21:15.794995Z | intellij file | +| 2017-10-09T10:43:56.532687Z | Added HTML files for api documentation based on uikit | +| 2017-10-06T12:08:16.603152Z | deleting old API documentation: new will be committed soon by Katerina | +| 2017-10-06T12:04:55.560134Z | copied from dnet40 | +| 2017-05-26T11:44:59.926816Z | removed warning for fundingStream queries | +| 2017-05-25T12:36:43.800409Z | warning and location of the api in the prod infra | +| 2017-03-29T13:58:34.013071Z | reformatted xml and new generated HTML | +| 2017-03-29T13:57:23.196971Z | changed pubdate | +| 2017-03-29T13:46:08.349593Z | added link to the OpenAIRE helpdesk | +| 2017-03-29T13:39:44.386894Z | fixed param hasWTFunding (instead of hasUKFunding) + list of supported funders | +| 2017-03-29T13:37:43.381141Z | param name is dateOfAcceptance not of collection | +| 2017-02-22T09:31:34.767373Z | #2630: informing that incremental harvesting is not supported and updated list of interesting OAI sets | +| 2016-01-18T10:38:57.125792Z | commented warning section | +| 2015-09-15T09:04:00.819955Z | added this week in the warning week | +| 2015-09-15T09:02:37.458839Z | updated supported funders and removed section about the TSV as it is only to be used by NOADs | +| 2015-09-15T08:56:37.943151Z | removed organizations OAI set in the examples. Added FP7Publications. | +| 2015-09-15T08:54:41.579385Z | Updated links to the guidelines | +| 2015-09-15T08:53:06.677011Z | OAI-PMH discards duplicates now | +| 2015-08-26T08:51:32.795385Z | added schema 0.3 as the latest schema | +| 2015-05-18T12:10:24.329058Z | csvn and tsv formats available for search api | +| 2015-03-20T10:54:31.069584Z | fixed tsv URL | +| 2015-03-20T10:49:46.639336Z | updated date | +| 2015-03-20T10:49:11.327980Z | added documentation for the projects2tsv endpoint | +| 2015-03-19T11:18:36.226626Z | minor changes to a couple of sentences | +| 2015-03-13T17:35:01.980176Z | updated the generated html | +| 2015-03-13T17:33:41.882951Z | added list of avaialble funding streams and those that are coming soon | +| 2015-03-13T17:33:02.339565Z | openaire compliance of OAI-PMH | +| 2015-02-04T14:16:56.528188Z | #1062: OAI-PMH and HTTP numbers are not the same becuase of duplicates | +| 2014-12-03T15:17:27.207961Z | #1031: title of eprints/dspace export | +| 2014-11-13T16:11:13.633046Z | Updated date and generated new html | +| 2014-11-13T16:08:12.045544Z | Fixed documentation about datasets | +| 2014-11-11T18:43:18.738678Z | Fixed documentation for publications | +| 2014-11-11T17:09:19.351093Z | added sortby parameter | +| 2014-09-17T09:05:38.726757Z | created tag folder for release | +| 2014-08-04T10:59:48.089720Z | Updated pubdate | +| 2014-08-04T10:58:22.814919Z | Overview cleanup | +| 2014-08-04T10:50:54.515588Z | added links to the latest available schema and documentation | +| 2014-07-24T14:09:49.733958Z | #690: HTTP API documentation for project and other updates. | +| 2014-06-06T08:41:45.731338Z | #550: making it clear we are delivering metadata only. Clenaup. | +| 2014-05-14T16:38:30.702554Z | updated date | +| 2014-05-14T16:35:05.787718Z | re-added OAI set for projects | +| 2014-04-30T10:42:18.355154Z | updated oxygen project with the correct tree structure | +| 2014-04-30T10:41:14.539090Z | Added and commented property to generate output in chunks | +| 2014-04-30T10:40:30.012256Z | mvn generates output with no chunks in a single file: api-doc.html | +| 2014-04-30T10:39:37.875730Z | Main docbook file renamed from book.xml to api-doc.xml | +| 2014-04-30T10:34:16.576722Z | updated OAI-PMH sets: now delivering only results and no other entities. | +| 2014-04-15T09:53:22.158487Z | copied dnet-api-http-doc to new dnet40 codebase | +| 2014-04-10T09:55:41.690052Z | ignore | +| 2014-04-10T09:53:59.192401Z | removed target/*classes from svn | +| 2014-04-09T10:46:05.757155Z | mavenized project. Generates html running mvn docbkx:generate-html. results are then in target/docbkx | +| 2014-04-09T09:18:26.268418Z | added links to xsd and xsd doc in the overview chapter | +| 2014-04-08T12:55:01.169556Z | ticket #300: updated doc for APIs | +| 2014-03-10T18:13:38.784171Z | not a maven project | +| 2014-03-10T18:13:18.180379Z | basic structure for API doc | +| 2014-03-10T13:50:02.957489Z | added files as generated by the archetype docbkx-quickstart-archetype v2.0.15 | +| 2014-03-10T13:45:30.505315Z | created module for HTTP API docbook | \ No newline at end of file diff --git a/docs/apis/terms.md b/docs/apis/terms.md new file mode 100644 index 0000000..0ec0154 --- /dev/null +++ b/docs/apis/terms.md @@ -0,0 +1,17 @@ +# Terms of use + +## Authentication & limits + +The OpenAIRE APIs are free-to-use by any third-party service and can be accessed over HTTPS both by authenticated and unauthenticated requests. The rate limit for the former type of requests is up to 7200 requests per hour, while the latter is up to 60 requests per hour. + +To make an authenticated request, you must first [register](https://services.openaire.eu/uoa-user-management/register.jsp). Then, you can go to the [personal access token page](https://develop.openaire.eu/user-info?errorCode=1&redirectUrl=%2Fpersonal-token) in your account, copy your token and use it for up to one hour, [find out more](./authenticated-requests). + +Our OAuth 2.0 implementation, conforms to the OpenID Connect specification, and is [OpenID Certified](https://openid.net/certification/). OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. For more information about OAuth2.0 please visit the [OAuth2.0 official site](https://oauth.net/2/). For more information about OpenID Connect please visit the [OpenID Connect official site](https://openid.net/connect/). Also, check [here](http://www.openaire.eu/privacy-policy) for more information on our Privacy Policy. + +## Quality of service + +OpenAIRE API services are running in production 24/7 within the OpenAIRE infrastructure premises deployed at the data center facilities of the Interdisciplinary Centre for Mathematical and Computational Modelling (ICM). + +## License + +OpenAIRE Graph license is CC-BY: the records returned by the service can be freely re-used by commercial and non-commercial partners under CC-BY license, hence as long as OpenAIRE is acknowledged as a data source. diff --git a/sidebars.js b/sidebars.js index abbf053..e6d2624 100644 --- a/sidebars.js +++ b/sidebars.js @@ -54,9 +54,37 @@ const sidebars = { ] }, { - type: "link", - label: "Public API", - href: "https://graph.openaire.eu/develop/overview.html" + type: 'category', + label: "Public APIs", + link: {type: 'doc', id: 'apis/home'}, + items: [ + { + type: 'category', + label: "Search API", + link: { type: 'doc', id: 'apis/search-api/search-api' }, + items: [ + { type: 'doc', id: 'apis/search-api/results' }, + { type: 'doc', id: 'apis/search-api/projects' }, + { type: 'doc', id: 'apis/search-api/response-metadata-format' }, + ] + }, + { + type: "link", + label: "ScholeXplorer API", + href: "https://api.scholexplorer.openaire.eu/swagger-ui/index.html?urls.primaryName=Scholexplorer%20API%20V2.0" + }, + { + type: "doc", + id: "apis/dspace-eprints-api", + }, + { + type: "doc", + id: "apis/broker-api" + }, + { type: 'doc', id: 'apis/terms' }, + { type: 'doc', id: 'apis/authenticated-requests' }, + { type: 'doc', id: 'apis/specification-changelog' }, + ] }, { type: 'category', diff --git a/static/resources/athenarc_fos_hierarchy.json b/static/resources/athenarc_fos_hierarchy.json new file mode 100644 index 0000000..2788bce --- /dev/null +++ b/static/resources/athenarc_fos_hierarchy.json @@ -0,0 +1 @@ +{"natural sciences": [{"mathematics": ["applied mathematics", "general mathematics", "numerical & computational mathematics", "statistics & probability"]}, {"computer and information sciences": ["computation theory & mathematics"]}, {"physical sciences": ["acoustics", "applied physics", "astronomy & astrophysics", "chemical physics", "fluids & plasmas", "general physics", "mathematical physics", "nuclear & particles physics", "optics"]}, {"chemical sciences": ["analytical chemistry", "general chemistry", "inorganic & nuclear chemistry", "medicinal & biomolecular chemistry", "organic chemistry", "physical chemistry", "polymers"]}, {"earth and related environmental sciences": ["environmental sciences", "geochemistry & geophysics", "geology", "meteorology & atmospheric sciences", "oceanography", "paleontology"]}, {"biological sciences": ["ecology", "entomology", "evolutionary biology", "marine biology & hydrobiology", "ornithology", "plant biology & botany", "zoology", "biotechnology"]}, {"other natural sciences": []}], "engineering and technology": [{"civil engineering": ["civil engineering"]}, {"electrical engineering, electronic engineering, information engineering": ["artificial intelligence & image processing", "computer hardware & architecture", "distributed computing", "information systems", "medical informatics", "networking & telecommunications", "software engineering", "electrical & electronic engineering", "energy", "optoelectronics & photonics"]}, {"mechanical engineering": ["aerospace & aeronautics", "automobile design & engineering", "mechanical engineering & transports"]}, {"chemical engineering": ["chemical engineering"]}, {"materials engineering": ["mining & metallurgy", "materials"]}, {"medical engineering": ["biomedical engineering", "bioinformatics"]}, {"environmental engineering": ["environmental engineering"]}, {"environmental biotechnology": ["environmental engineering"]}, {"industrial biotechnology": ["industrial engineering & automation"]}, {"nano-technology": ["nanoscience & nanotechnology"]}, {"other engineering and technologies": ["geological & geomatics engineering", "mining & metallurgy", "operations research", "architecture", "building & construction", "design practice & management", "urban & regional planning", "energy", "optoelectronics & photonics", "strategic, defence & security studies"]}], "medical and health sciences": [{"basic medicine": ["anatomy & morphology", "biochemistry & molecular biology", "biophysics", "developmental biology", "genetics & heredity", "microbiology", "microscopy", "mycology & parasitology", "nutrition & dietetics", "physiology", "toxicology", "virology"]}, {"clinical medicine": ["allergy", "anesthesiology", "arthritis & rheumatology", "cardiovascular system & hematology", "complementary & alternative medicine", "dentistry", "dermatology & venereal diseases", "emergency & critical care medicine", "endocrinology & metabolism", "environmental & occupational health", "gastroenterology & hepatology", "general & internal medicine", "general clinical medicine", "geriatrics", "immunology", "legal & forensic medicine", "neurology & neurosurgery", "nuclear medicine & medical imaging", "obstetrics & reproductive medicine", "oncology & carcinogenesis", "ophthalmology & optometry", "orthopedics", "otorhinolaryngology", "pathology", "pediatrics", "pharmacology & pharmacy", "psychiatry", "respiratory system", "sport sciences", "surgery", "tropical medicine", "urology & nephrology"]}, {"health sciences": ["anatomy & morphology", "biochemistry & molecular biology", "biophysics", "developmental biology", "genetics & heredity", "microbiology", "microscopy", "mycology & parasitology", "nutrition & dietetics", "physiology", "toxicology", "virology"]}, {"medical biotechnology": []}, {"other medical science": ["epidemiology", "gerontology", "health policy & services", "nursing", "public health", "rehabilitation", "speech-language pathology & audiology", "substance abuse"]}], "agricultural and veterinary sciences": [{"agriculture, forestry, and fisheries": ["forestry", "fisheries", "agronomy & agriculture"]}, {"animal and dairy science": ["dairy & animal science"]}, {"veterinary science": ["veterinary sciences"]}, {"agricultural biotechnology": ["food science"]}, {"other agricultural sciences": ["horticulture", "food science"]}], "social sciences": [{"psychology and cognitive sciences": ["languages & linguistics", "behavioral science & comparative psychology", "clinical psychology", "developmental & child psychology", "experimental psychology", "general psychology & cognitive sciences", "human factors", "psychoanalysis", "social psychology"]}, {"economics and business": ["accounting", "agricultural economics & policy", "business & management", "development studies", "econometrics ", "economic theory", "economics", "finance", "industrial relations", "logistics & transportation", "marketing", "sport, leisure & tourism"]}, {"education": ["education"]}, {"sociology": ["social sciences methods", "sociology"]}, {"law": ["criminology", "law"]}, {"political science": ["international relations", "political science & public administration"]}, {"social and economic geography": ["cultural studies", "demography", "geography"]}, {"media and communications": ["communication & media studies"]}, {"other social sciences": ["criminology", "family studies", "gender studies", "information & library sciences", "science studies", "social work"]}], "humanities and the arts": [{"history and archaeology": ["anthropology", "archaeology", "classics", "history", "history of science, technology & medicine", "history of social sciences"]}, {"languages and literature": ["languages & linguistics", "literary studies"]}, {"philosophy, ethics and religion": ["applied ethics", "philosophy", "religions & theology"]}, {"arts": ["art practice, history & theory", "drama & theater", "folklore", "music"]}, {"other humanities": []}]} \ No newline at end of file