You can use the Ricgraph REST API to get data from Ricgraph, or to execute predefined queries in Ricgraph and Ricgraph Explorer, in such a way that your code is not dependent on any Ricgraph code. In your own code, you do not need to include any of the Ricgraph dependencies, nor include ricgraph.py or ricgraph_explorer.py. You can use the Ricgraph REST API to programmatically get items from Ricgraph, as an alternative to using the user interface Ricgraph Explorer.
Note that this will only work if someone has a running Ricgraph and Ricgraph Explorer instance available, which you can access over the web. That someone can be yourself, where you run Ricgraph and Ricgraph Explorer on your own computer or use a cloud service such as SURF Research Cloud, or it can be someone else, who is doing that for you or for a community of users.
If you use the Ricgraph REST API, will get these results in a JSON format. The Ricgraph REST API uses the OpenAPI standard. It gives access to Ricgraph function calls both in ricgraph.py and in ricgraph_explorer.py. Read more about REST (representational state transfer), or read more about API (application programming interface).
On this page, you can learn more about:
Return to main README.md file.
The Ricgraph REST API is part of Ricgraph Explorer. Read how to start Ricgraph Explorer.
Depending on your needs, you might also want to read:
- Install and use a service unit file to run Ricgraph Explorer and the Ricgraph REST API.
- Use Apache, WSGI, and ASGI to make Ricgraph Explorer and the Ricgraph REST API accessible from outside your virtual machine.
A call to a REST API consists of a hostname, sometimes a port number, the path /api/, followed by a REST API endpoint. For example, in
http://127.0.0.1:3030/api/person/search?value=John+Doe
/person/search is the endpoint, value the name of a query parameter to the REST API, and John+Doe the value for the query parameter.
You can use the online documentation in Ricgraph Explorer for the REST API. It lists the various endpoints and parameters, and you can try out each endpoint with values for parameters as you like. To do this, click the "REST API doc" button in the top bar of Ricgraph Explorer, and you will get an explanation how to do this. See the figure below, that shows part of the Home page of Ricgraph Explorer (click on it to enlarge).
As an alternative, you can also read the Ricgraph REST API documentation page, that is auto generated from the OpenAPI yaml specification file, but it only lists the end points and parameters available and there is no try out feature.
Run script convert_openapi_to_mddoc.py in directory
maintenance_scripts.
Use the python in the bin directory of your virtual environment.