What is $DATAVERSE_ALIAS? (How to list datasets in a dataverse)

31 views
Skip to first unread message

wou...@triply.cc

unread,
Jul 25, 2017, 3:18:39 AM7/25/17
to Dataverse Users Community
Hi DataVerse community!,

I got stuck while reading the DataVerse API documentation over at

Section “List datasets in a dataverse” contains the following request:

```
curl -u $API_TOKEN: https://$HOSTNAME/dvn/api/data-deposit/v1.1/swordv2/collection/dataverse/$DATAVERSE_ALIAS
```

What is `$DATAVERSE_ALIAS'?  AFAICT it is currently not described in
the documentation.

---
Cheers!,
Wouter.

Kraffmiller, Stephen E

unread,
Jul 25, 2017, 9:18:30 AM7/25/17
to dataverse...@googlegroups.com
The Dataverse alias is the code for a dataverse that goes into its home url.


So for the “Cell Counts” Dataverse the alias is ‘retinas’

We’ll take a look at the documentation and see if we can make it clearer.

Cheers,
Steve Kraffmiller
IQSS


--
You received this message because you are subscribed to the Google Groups "Dataverse Users Community" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dataverse-commu...@googlegroups.com.
To post to this group, send email to dataverse...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/dataverse-community/a6200197-ca63-432e-9985-5cbdc3257ea5%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Wouter Beek

unread,
Jul 25, 2017, 9:36:12 AM7/25/17
to dataverse...@googlegroups.com
Dear Steve,

Thank you for clarifying. The relationship that you describe between
the `$DATAVERSE_ALIAS` and a URI path segment was not clear to me from
the documentation.

I'm still having difficulty finding a URI that contains a path segment
that denoted the Dataverse alias. I am able to perform the first
request that is described in the SWORD API documentation chapter:
“Retrieve SWORD service document” That request is made against the
following URI:

```uri
https://datasets.socialhistory.org/dvn/api/data-deposit/v1.1/swordv2/service-document
```

The reply body contains the following:

```xml
<service xmlns="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom"><workspace><atom:title
type="text">IISH</atom:title></workspace><generator
xmlns="http://www.w3.org/2005/Atom" uri="http://www.swordapp.org/"
version="2.0"/><version
xmlns="http://purl.org/net/sword/terms/">2.0</version></service>
```

Does this contain the Dataverse alias (maybe "IISH")?

---
Cheers!,
Wouter.


On 7/25/17, Kraffmiller, Stephen E <skraff...@hmdc.harvard.edu> wrote:
> The Dataverse alias is the code for a dataverse that goes into its home
> url.
>
> https://dataverse.harvard.edu/dataverse/retinas
>
> So for the “Cell Counts” Dataverse the alias is ‘retinas’
>
> We’ll take a look at the documentation and see if we can make it clearer.
>
> Cheers,
> Steve Kraffmiller
> IQSS
>
>
> On Jul 25, 2017, at 3:18 AM, wou...@triply.cc<mailto:wou...@triply.cc>
> wrote:
>
> Hi DataVerse community!,
>
> I got stuck while reading the DataVerse API documentation over at
> http://guides.dataverse.org/en/4.7/api/sword.html
>
> Section “List datasets in a dataverse” contains the following request:
>
> ```
> curl -u $API_TOKEN:
> https://$HOSTNAME/dvn/api/data-deposit/v1.1/swordv2/collection/dataverse/$DATAVERSE_ALIAS<https://$hostname/dvn/api/data-deposit/v1.1/swordv2/collection/dataverse/$DATAVERSE_ALIAS>
> ```
>
> What is `$DATAVERSE_ALIAS'? AFAICT it is currently not described in
> the documentation.
>
> ---
> Cheers!,
> Wouter.
>
>
> --
> You received this message because you are subscribed to the Google Groups
> "Dataverse Users Community" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to
> dataverse-commu...@googlegroups.com<mailto:dataverse-commu...@googlegroups.com>.
> To post to this group, send email to
> dataverse...@googlegroups.com<mailto:dataverse...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/dataverse-community/a6200197-ca63-432e-9985-5cbdc3257ea5%40googlegroups.com<https://urldefense.proofpoint.com/v2/url?u=https-3A__groups.google.com_d_msgid_dataverse-2Dcommunity_a6200197-2Dca63-2D432e-2D9985-2D5cbdc3257ea5-2540googlegroups.com-3Futm-5Fmedium-3Demail-26utm-5Fsource-3Dfooter&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=d7bbsLIcERTG2Qe_gE_iKH1z80JxaTHhJpRXaS4mxwM&m=qRAekjRE8K4_CMR1U775e-tsXQI8ruJPvrI-VPvyhpE&s=orbx9xiBUsvnSHufjvhUMe9aCABvzUndVDkXEwisuGg&e=>.
> For more options, visit
> https://groups.google.com/d/optout<https://urldefense.proofpoint.com/v2/url?u=https-3A__groups.google.com_d_optout&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=d7bbsLIcERTG2Qe_gE_iKH1z80JxaTHhJpRXaS4mxwM&m=qRAekjRE8K4_CMR1U775e-tsXQI8ruJPvrI-VPvyhpE&s=1JnyJxMgi3NO3LezA3Jy4b2nlkiLWBvuQvGqn3WlfFg&e=>.
>
> --
> You received this message because you are subscribed to a topic in the
> Google Groups "Dataverse Users Community" group.
> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/dataverse-community/G5qpjegSUhM/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to
> dataverse-commu...@googlegroups.com.
> To post to this group, send email to dataverse...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/dataverse-community/F5BA1837-742B-4C69-ACDD-B625B1D26802%40hmdc.harvard.edu.
> For more options, visit https://groups.google.com/d/optout.
>


--
---
Best regards,
Wouter Beek.

Email: woute...@triply.cc
WWW: triply.cc
Tel: +31647674624

Kraffmiller, Stephen E

unread,
Jul 25, 2017, 9:52:15 AM7/25/17
to dataverse...@googlegroups.com
Hi Wouter,

Yes. It looks like your top-level dataverse has the alias ‘IISH’. I don’t have permissions on it so I’m not able to get the results of the ‘List datasets in Dataverse’ API call, but it should be:


To get the list of datasets in lower level dataverses you’ll have to substitute their respective aliases, such as:

coinproduction
-or-
RemarkableStrikes

etc.

Let me know if you have any more questions.

Thanks,
Steve



To unsubscribe from this group and stop receiving emails from it, send an email to dataverse-commu...@googlegroups.com.

To post to this group, send email to dataverse...@googlegroups.com.

Philip Durbin

unread,
Jul 27, 2017, 9:28:28 AM7/27/17
to dataverse...@googlegroups.com
I agree that the SWORD documentation is a bit confusing and I wrote it!

When I use curl commands in documentation my mind tends to wander to shell programming mode and I use shell variables such as $DATAVERSE_ALIAS and $API_TOKEN. The idea with these shell variables is that you can set them once and then copy and paste the curl commands like this:

export API_TOKEN=9ca6ed71-1331-47d1-a5aa-602242152d9c

export HOSTNAME=dataverse.harvard.edu

curl -u $API_TOKEN: https://$HOSTNAME/dvn/api/data-deposit/v1.1/swordv2/service-document

That was my thinking anyway. Wouter, you would be very welcome to open an issue at https://github.com/IQSS/dataverse/issues asking for how you'd like the API Guide to be improved!

I did want to weight in on the output of the SWORD Service Document. The XML output Wouter provided indicates that he does not have permission to create datasets in any dataverses. Each dataverse you have permission to deposit into should have a corresponding "collection" element and URL like this:

```
<?xml version="1.0"?>

<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace>
    <atom:title type="text">Harvard Dataverse</atom:title>
    <collection href="https://dataverse.harvard.edu/dvn/api/data-deposit/v1.1/swordv2/collection/dataverse/biomedcentral">
      <atom:title type="text">BioMed Central Dataverse</atom:title>
      <collectionPolicy xmlns="http://purl.org/net/sword/terms/">http://best-practices.dataverse.org/harvard-policies/harvard-api-tou.html</collectionPolicy>
      <mediation xmlns="http://purl.org/net/sword/terms/">false</mediation>
      <acceptPackaging xmlns="http://purl.org/net/sword/terms/">http://purl.org/net/sword/package/SimpleZip</acceptPackaging>
    </collection>
...
    <collection href="https://dataverse.harvard.edu/dvn/api/data-deposit/v1.1/swordv2/collection/dataverse/accounting">
      <atom:title type="text">Accounting related Dataverse</atom:title>
      <collectionPolicy xmlns="http://purl.org/net/sword/terms/">http://best-practices.dataverse.org/harvard-policies/harvard-api-tou.html</collectionPolicy>
      <mediation xmlns="http://purl.org/net/sword/terms/">false</mediation>
      <acceptPackaging xmlns="http://purl.org/net/sword/terms/">http://purl.org/net/sword/package/SimpleZip</acceptPackaging>
    </collection>

  </workspace>
  <generator xmlns="http://www.w3.org/2005/Atom" uri="http://www.swordapp.org/" version="2.0"/>
  <version xmlns="http://purl.org/net/sword/terms/">2.0</version>
  <maxUploadSize xmlns="http://purl.org/net/sword/terms/">2147483647</maxUploadSize>
</service>
```

The SWORD Service Document is the starting point for depositing data. When you ask for the Service Document, you're basically asking, "Where can I deposit data?" You get back a list of dataverses (a list of "collection" elements in XML) that you can deposit into or query to get a list of existing datasets. Basically, SWORD is only useful if you have "write" access to at least one dataverse/collection. That is to say, SWORD is oriented toward depositing data.

I hope this helps!

Phil


On Jul 25, 2017, at 3:18 AM, wou...@triply.cc<mailto:wouter@triply.cc>

wrote:

Hi DataVerse community!,

I got stuck while reading the DataVerse API documentation over at
http://guides.dataverse.org/en/4.7/api/sword.html

Section “List datasets in a dataverse” contains the following request:

```
curl -u $API_TOKEN:
https://$HOSTNAME/dvn/api/data-deposit/v1.1/swordv2/collection/dataverse/$DATAVERSE_ALIAS<https://$hostname/dvn/api/data-deposit/v1.1/swordv2/collection/dataverse/$DATAVERSE_ALIAS>
```

What is `$DATAVERSE_ALIAS'?  AFAICT it is currently not described in
the documentation.

---
Cheers!,
Wouter.


--
You received this message because you are subscribed to the Google Groups
"Dataverse Users Community" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to

To post to this group, send email to

To view this discussion on the web visit
https://groups.google.com/d/msgid/dataverse-community/a6200197-ca63-432e-9985-5cbdc3257ea5%40googlegroups.com<https://urldefense.proofpoint.com/v2/url?u=https-3A__groups.google.com_d_msgid_dataverse-2Dcommunity_a6200197-2Dca63-2D432e-2D9985-2D5cbdc3257ea5-2540googlegroups.com-3Futm-5Fmedium-3Demail-26utm-5Fsource-3Dfooter&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=d7bbsLIcERTG2Qe_gE_iKH1z80JxaTHhJpRXaS4mxwM&m=qRAekjRE8K4_CMR1U775e-tsXQI8ruJPvrI-VPvyhpE&s=orbx9xiBUsvnSHufjvhUMe9aCABvzUndVDkXEwisuGg&e=>.
For more options, visit
https://groups.google.com/d/optout<https://urldefense.proofpoint.com/v2/url?u=https-3A__groups.google.com_d_optout&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=d7bbsLIcERTG2Qe_gE_iKH1z80JxaTHhJpRXaS4mxwM&m=qRAekjRE8K4_CMR1U775e-tsXQI8ruJPvrI-VPvyhpE&s=1JnyJxMgi3NO3LezA3Jy4b2nlkiLWBvuQvGqn3WlfFg&e=>.

--
You received this message because you are subscribed to a topic in the
Google Groups "Dataverse Users Community" group.
To unsubscribe from this topic, visit
https://groups.google.com/d/topic/dataverse-community/G5qpjegSUhM/unsubscribe.
To unsubscribe from this group and all its topics, send an email to


--
---
Best regards,
Wouter Beek.

Email: woute...@triply.cc
WWW: triply.cc
Tel: +31647674624

--
You received this message because you are subscribed to the Google Groups "Dataverse Users Community" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dataverse-community+unsub...@googlegroups.com.
To post to this group, send email to dataverse-community@googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "Dataverse Users Community" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dataverse-community+unsub...@googlegroups.com.
To post to this group, send email to dataverse-community@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/dataverse-community/9D44A8BC-83B5-4509-9670-6D010DB6CA92%40hmdc.harvard.edu.

For more options, visit https://groups.google.com/d/optout.



--

Wouter Beek

unread,
Jul 27, 2017, 3:12:14 PM7/27/17
to dataverse...@googlegroups.com
Hi Philip,

> Basically, SWORD is only useful if you have "write"
> access to at least one dataverse/collection. That is to say, SWORD is
> oriented toward depositing data.

That explains a lot: I am interested in reading metadata (but not in
writing data). So SWORD is then maybe the wrong API for doing that.

Philip Durbin

unread,
Jul 27, 2017, 3:25:27 PM7/27/17
to dataverse...@googlegroups.com
If you're interested in reading metadata you could try URLs like this: https://datasets.socialhistory.org/api/datasets/:persistentId?persistentId=hdl:10622/OLN2UJ

--
You received this message because you are subscribed to the Google Groups "Dataverse Users Community" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dataverse-community+unsub...@googlegroups.com.
To post to this group, send email to dataverse-community@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/dataverse-community/CAEh2WcPNaoy9EOdJqDLELAtk%2B1jRdZgSF8_naNqnzWT3ne9b1g%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.
Reply all
Reply to author
Forward
0 new messages