Page tree
Skip to end of metadata
Go to start of metadata

Note:  All documentation should be considered to be in-progress, working documents unless otherwise noted.

The documents in this section describe how to use the RMap API. For a more in-depth description of the RMap data model, view the Data Model documentation.  You can also download a complete summary of all API calls available.

RMap sandboxes

There are two publicly available instances of the RMap software that can be used as sandboxes.  Neither of these instances are persistent at this stage, though historically test has been used for testing out new batches, and demo data is for higher quality data.

Test (https://test.rmap-hub.org)

The test site is intended for experimental data and test runs.  It contains around 4.3 million experimental RMap DiSCOs, many of which were produced by IEEE to represent their articles. Smaller samples were harvested from SHARE, OSF, ACM, DataCite, and Portico. The database includes a lot of repetition and mistakes.  Please feel free to use this site to create your own test data. 

Demo (https://demo.rmap-hub.org)

The demo site currently contains only a few thousand RMap DiSCOs.  Historically, this instance has been used for live demos and so contains a small set of interesting examples and higher quality data.  Users are welcome to create data in demo, but recommend experimenting on test to improve your DiSCO quality first.

Read-only access

Each of the API paths documented below can be appended to the root RMap API path. A demo instance of RMap is available at the following address:

https://demo.rmap-hub.org/api

Only functions that create data require authentication. So, for example, you can read a DiSCO using the following CURL command (pasting the URL part into your browser also works!):

curl -H "Accept: text/turtle" -X GET https://demo.rmap-hub.org/api/discos/rmap%3Armd18n8xfs

Note: Visual representations of some paths are available through the demo website. If your API path matches the following pattern it can be easily toggled to the visual version by replacing /api/ with /app/ as follows:

#API path
https://demo.rmap-hub.org/api/{resources|discos|events|agents}/{http_encoded_resource_uri}
#visualization:
https://demo.rmap-hub.org/app/{resources|discos|events|agents}/{http_encoded_resource_uri}

Here are some sample visualization that support this simple conversion between the API and GUI paths :

Write access

To create DiSCOs in RMap, you will need to generate an RMap Agent for yourself.  You can do this by logging into the RMap website using your Google, Twitter, or ORCID account.  Once you've logged in, you will need to follow the two steps on the Welcome page to generate working API keys.  Please note that all data pushed into RMap will be public. 

To create API keys for the demo site, log into the following website and follow the steps: https//demo.rmap-hub.org/app 

Once you have create a key and downloaded the key file, a curl command to create a new DiSCO, for example, might look like this:

curl -u $(<rmap.key)
	-X POST
	-d @disco.rdf
	--header "Content-Type:application/rdf+xml"
	https://demo.rmap-hub.org/api/discos

In this case:

  • "rmap.key" is a simple text file containing {key}:{secret}.  You can download this file through the web GUI. 
  • "disco.rdf" is a text file containing your DiSCO RDF.  The content type should match the type defined in the header.

Some example DiSCOs can be found in the RMap test data. Note that some of these are deliberately faulty for testing.  discoA.jsonld, .rdf, or .ttl, and discoBv1-4.rdf are working examples.

API paths

The documentation for the API paths is split according to the major sub-directories. Below is an overview of what each of these paths contain and links to the detailed documentation.

/discos 

RMap DiSCOs are the focal component of the RMap data model. DiSCO is short for "Distributed Scholarly Compound Object".  They contain an aggregation of resources and assertions about those resources as a graph.  The DiSCOs API path supports management of, and access to DiSCOs in RMap.

view documentation

/agents

RMap Agents are people or organizations that can contribute to RMap.  Anyone can sign up to become an RMap Agent by registering through the web application.  

Agents are associated with each RMap DiSCO they create in RMap.  The Agents API path supports retrieval of Agent data including a list of DiSCOs created by specific Agents.

view documentation

/events

RMap Events capture information about changes to the RMap database.  They also inform the status of a DiSCO or Agent and include a link to the RMap Agent that triggered the Event.  The Event API supports retrieval of specific Event data.

view documentation

/resources

Resources refer to rdf:Resources in the RMap triplestore.  They refer to any URI referenced as either the Subject or Object of an RDF triple. RMap DiSCOs and Agents are composed of triples.  The Resources API allows you to look at what RMap "knows" about a particular Resource.  For example, you may wish to know what triples in RMap contain a particular Resource URI, or what DiSCOs mention it.

view documentation

/stmts

Stmts refers to rdf:Statements in the RMap triplestore.  The stmts API allows you, for example, to look up a particular triple in RMap and see which Agents have asserted it.

view documentation


  • No labels
Write a comment…