Skip to content

ricgraph_restapi_gendoc.md

Latest commit

 

History

History
685 lines (262 loc) · 18.2 KB

ricgraph_restapi_gendoc.md

File metadata and controls

685 lines (262 loc) · 18.2 KB

Ricgraph - Research in context graph REST API

This REST API documentation has been generated automatically.

REST API version 1.0.0.

What to find on this page?

This is the documentation page for the Ricgraph REST API. You can use the Ricgraph REST API to programmatically get items from Ricgraph, as an alternative to using the user interface. You will get these items in a JSON format.

How to use

In the left column of this page, you can explore the calls (i.e., the REST API operations) that are available. You can also try them out, by selecting a call, entering values in the 'Query-string parameters' subsection of the 'Request' section, and clicking the 'Try' button. Next, a gray tabbed box will appear. In the 'Response' tab of that box, you will get the JSON response. In the 'CURL' tab of that box, you will get a curl call with an URL (web link) that you can use in a browser or in your code. You don't need to provide authentication to use these calls.

Technicalities

The Ricgraph REST API uses the OpenAPI standard. It gives access to Ricgraph function calls. Read more about REST (representational state transfer), or read more about API (application programming interface).

Base URL

URL Description
/api

Endpoints

Method Endpoint Description
GET GET /person/search Search for a person
GET GET /person/all_information Show all information related to this person
GET GET /person/share_researchresults Find persons that share any research result types with this person
GET GET /person/collaborating_organizations Find organizations that this person collaborates with
GET GET /person/enrich Find information harvested from other source systems, not present in this source system
GET GET /organization/search Search for a (sub-)organization
GET GET /organization/all_information Show all information related to this organization
GET GET /organization/information_persons_results Find any information from persons or their results in this organization
GET GET /organization/enrich Find information harvested from other source systems, not present in this source system
GET GET /opensciencelandscape/explorecollaborations Explore collaborations
GET GET /competence/search Search for a skill, expertise area or research area
GET GET /competence/all_information Show all information related to this competence
GET GET /broad_search Search for anything (broad search)
GET GET /advanced_search Advanced search
GET GET /get_all_personroot_nodes Find all person-root nodes of this node
GET GET /get_all_neighbor_nodes Find all neighbor nodes of this node
GET GET /get_ricgraph_info Get information about Ricgraph

GET /person/search

Search for a person

Parameters

Name Type Required Description
value string False Search for a value in Ricgraph field value
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /person/all_information

Show all information related to this person

Parameters

Name Type Required Description
key string True Search for a value in Ricgraph field _key
year_first string False Search for a research result from year >= year_first. If you include this field, only research results will be returned.
year_last string False Search for a research result from year <= year_last. If you include this field, only research results will be returned.
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /person/share_researchresults

Find persons that share any research result types with this person

Parameters

Name Type Required Description
key string True Search for a value in Ricgraph field _key
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /person/collaborating_organizations

Find organizations that this person collaborates with

With this call you will get an overview of organizations that his person collaborates with. A person X from organization A collaborates with a person Y from organization B if X and Y have both contributed to the same research result.

Parameters

Name Type Required Description
key string True Search for a value in Ricgraph field _key
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /person/enrich

Find information harvested from other source systems, not present in this source system

The process of improving or enhancing information in a source system is called enriching that source system. This is only possible if you have harvested more than one source system. By using information found in one or more other harvested systems, information in this source system can be improved or enhanced. With this call you can enter a name of one of your source systems. Ricgraph will show what information can be added to this source system, based on the information harvested from other source systems. This call enriches persons. Note that if you specify category_want, you will need to add category person too, since otherwise you will not be able to find person_identifying_nodes (the nodes to add the newly found information to).

Parameters

Name Type Required Description
key string True Search for a value in Ricgraph field _key
name_want array False Return only neighbor nodes whose field name matches any value in the provided list; if the list is empty, return all neighbor nodes regardless of their field name
category_want array False Return only neighbor nodes whose field category matches any value in the provided list; if the list is empty, return all neighbor nodes regardless of their field category
source_system string True The name of the source system you would like to enrich
year_first string False Search for a research result from year >= year_first. If you include this field, only research results will be returned.
year_last string False Search for a research result from year <= year_last. If you include this field, only research results will be returned.
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /organization/search

Search for a (sub-)organization

Parameters

Name Type Required Description
value string False Search for a value in Ricgraph field value
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /organization/all_information

Show all information related to this organization

Parameters

Name Type Required Description
key string True Search for a value in Ricgraph field _key
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /organization/information_persons_results

Find any information from persons or their results in this organization

Parameters

Name Type Required Description
key string True Search for a value in Ricgraph field _key
name_want array False Return only neighbor nodes whose field name matches any value in the provided list; if the list is empty, return all neighbor nodes regardless of their field name
category_want array False Return only neighbor nodes whose field category matches any value in the provided list; if the list is empty, return all neighbor nodes regardless of their field category
year_first string False Search for a research result from year >= year_first. If you include this field, only research results will be returned.
year_last string False Search for a research result from year <= year_last. If you include this field, only research results will be returned.
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /organization/enrich

Find information harvested from other source systems, not present in this source system

The process of improving or enhancing information in a source system is called enriching that source system. This is only possible if you have harvested more than one source system. By using information found in one or more other harvested systems, information in this source system can be improved or enhanced. With this call you can enter a name of one of your source systems. Ricgraph will show what information can be added to this source system, based on the information harvested from other source systems. This call enriches organizations. It is different compared to the REST API call /person/enrich, since that call also returns information that allows to you find the node to enrich in the source system you specify. The REST API call /organization/enrich does NOT returns that information (yet).

Parameters

Name Type Required Description
key string True Search for a value in Ricgraph field _key
name_want array False Return only neighbor nodes whose field name matches any value in the provided list; if the list is empty, return all neighbor nodes regardless of their field name
category_want array False Return only neighbor nodes whose field category matches any value in the provided list; if the list is empty, return all neighbor nodes regardless of their field category
source_system string True The name of the source system you would like to enrich
year_first string False Search for a research result from year >= year_first. If you include this field, only research results will be returned.
year_last string False Search for a research result from year <= year_last. If you include this field, only research results will be returned.
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /opensciencelandscape/explorecollaborations

Explore collaborations

Explore collaborations between (sub-)organizations. This function will return a full HTML page in the 'results' field of the response. If this 'results' field is empty, there were either no collaborations, or one or more invalid field values have been entered. Unfortunately, at the moment, there is no way to return error messages for the latter case. The REST API includes the text of the following four D3 JavaScript libraries in its response. These libraries can be found at https://github.com/UtrechtUniversity/ricgraph/tree/main/ricgraph_explorer/static.

  • d3.v7.min.js
  • d3-chord.v3.min.js
  • d3-scale-chromatic.v1.min.js
  • d3-sankey.v0.12.3.min.js

Parameters

Name Type Required Description
start_organization string True Type the name for start_organization. This field may either be a full (sub-)organization name, or a prefix of a (sub-)organization.
collaborating_organization string False Type the name for collaborating_organization. This field may either be a full (sub-)organization name, or a prefix of a (sub-)organization. It may also be empty, in that case the collaborations from start_organization to any (sub-)organization will be found.
researchresult_category array False Restrict the collaborations to research results of a specific category. You can enter one or more categories. If you leave it empty, collaborations having any research result type will be found.

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /competence/search

Search for a skill, expertise area or research area

Parameters

Name Type Required Description
value string False Search for a value in Ricgraph field value
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /competence/all_information

Show all information related to this competence

Parameters

Name Type Required Description
key string True Search for a value in Ricgraph field _key
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /broad_search

Search for anything (broad search)

Parameters

Name Type Required Description
value string False Search for a value in Ricgraph field value
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /advanced_search

Advanced search

The fields you enter are case-sensitive and use exact match search. If you enter values in more than one field, these fields are combined using AND.

Parameters

Name Type Required Description
name string False Search for a value in Ricgraph field name
category string False Search for a value in Ricgraph field category
value string False Search for a value in Ricgraph field value
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /get_all_personroot_nodes

Find all person-root nodes of this node

Parameters

Name Type Required Description
key string True Search for a value in Ricgraph field _key
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /get_all_neighbor_nodes

Find all neighbor nodes of this node

Parameters

Name Type Required Description
key string True Search for a value in Ricgraph field _key
name_want array False Return only neighbor nodes whose field name matches any value in the provided list; if the list is empty, return all neighbor nodes regardless of their field name
name_dontwant array False Return only neighbor nodes whose field name does not match any value in the provided list; if the list is empty, return all neighbor nodes regardless of their field name
category_want array False Return only neighbor nodes whose field category matches any value in the provided list; if the list is empty, return all neighbor nodes regardless of their field category
category_dontwant array False Return only neighbor nodes whose field category does not match any value in the provided list; if the list is empty, return all neighbor nodes regardless of their field category
max_nr_items string False The maximum number of items to return, or 0 to return all items

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search

GET /get_ricgraph_info

Get information about Ricgraph

Parameters

Name Type Required Description
ricgraph_info string True Get information about Ricgraph. Some of this information is dependent on the data in your Ricgraph instance and on the systems you have harvested, and some of it is not. There are four types of information that you can retrieve, as indicated in the list below. Each information type has its own fields. You can query an item to find out what fields it contains.

  • ricgraph_cacheinfo: information about the cache Ricgraph uses, and the size of that cache.

  • ricgraph_harvestinfo: information about the sources that Ricgraph has harvested, and the number of nodes and edges.

  • ricgraph_nodeinfo: information about nodes in Ricgraph, and their fields and field values.

  • ricgraph_systeminfo: information about Ricgraph and Ricgraph Explorer. |

Responses

  • 200: OK

  • 250: Nothing found

  • 251: Invalid search