Beginner friendly API documentation

[pdurbin]

As I mentioned in the "Upcoming talk on the Dataverse API" thread on the mailing list, I'm adding some more introductory material to the guides to explain what Dataverse APIs are and how they can be used by support teams and others are not deeply technical and programmer-y: https://groups.google.com/d/msg/dataverse-community/V5WkMGDS4VI/maxXTdmzDwAJ

I don't plan to create a ton of diagrams but here's an example of what I've come up with so far:

I'm constantly deploying some proposed changes the the one above to this server if anyone would like a sneak peek: https://dev2.dataverse.org/guides/

I may or may not try to address other smallish issues flagged as "API Guide" while I'm in there: Feature: API Guide

Here's a screenshot of those many issues:

[sbarbosadataverse]

Thanks, Phil! ᐧ

…

On Mon, Aug 12, 2019 at 10:26 AM Philip Durbin ***@***.***> wrote: As I mentioned in the "Upcoming talk on the Dataverse API" thread on the mailing list, I'm adding some more introductory material to the guides to explain what Dataverse APIs are and how they can be used by support teams and others are not deeply technical and programmer-y: https://groups.google.com/d/msg/dataverse-community/V5WkMGDS4VI/maxXTdmzDwAJ <https://urldefense.proofpoint.com/v2/url?u=https-3A__groups.google.com_d_msg_dataverse-2Dcommunity_V5WkMGDS4VI_maxXTdmzDwAJ&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=8R6PzVqt1PEocauQgZMGXsGz29-nb19M7eqlo1d8EVs&m=7RArAasjvCTVW4mmarg7Pylk--ECPZnZ2DDPqRVsgFM&s=-k4a4ns1iIpyLA1JCfTO1BLCSQeC7KT4Bcw8gecNFY0&e=> I don't plan to create a ton of diagrams but here's an example of what I've come up with so far: [image: Screen Shot 2019-08-12 at 10 22 03 AM] <https://urldefense.proofpoint.com/v2/url?u=https-3A__user-2Dimages.githubusercontent.com_21006_62872230-2D10ff1600-2Dbceb-2D11e9-2D8cbb-2D58cfc7a3538f.png&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=8R6PzVqt1PEocauQgZMGXsGz29-nb19M7eqlo1d8EVs&m=7RArAasjvCTVW4mmarg7Pylk--ECPZnZ2DDPqRVsgFM&s=cCtOtbkLhWg_tLbkfl98zK5NYYOqW4SqHLEEewjJYwQ&e=> I'm constantly deploying some proposed changes the the one above to this server if anyone would like a sneak peek: https://dev2.dataverse.org/guides/ <https://urldefense.proofpoint.com/v2/url?u=https-3A__dev2.dataverse.org_guides_&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=8R6PzVqt1PEocauQgZMGXsGz29-nb19M7eqlo1d8EVs&m=7RArAasjvCTVW4mmarg7Pylk--ECPZnZ2DDPqRVsgFM&s=ce_jKiP4vlWaOXjbVjVfQHjgf6wJBogcYwERcIJOUSU&e=> I may or may not try to address other smallish issues flagged as "API Guide" while I'm in there: https://github.com/IQSS/dataverse/labels/Feature%3A%20API%20Guide <https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_IQSS_dataverse_labels_Feature-253A-2520API-2520Guide&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=8R6PzVqt1PEocauQgZMGXsGz29-nb19M7eqlo1d8EVs&m=7RArAasjvCTVW4mmarg7Pylk--ECPZnZ2DDPqRVsgFM&s=-J7c3AaJC7JAnlFuqKgBXj5cDE8sQ3PVIUS7tyY9rHk&e=> Here's a screenshot of those many issues: [image: Issues_·IQSS_dataverse-_2019-08-12_10 24 01] <https://urldefense.proofpoint.com/v2/url?u=https-3A__user-2Dimages.githubusercontent.com_21006_62872431-2D7a7f2480-2Dbceb-2D11e9-2D8344-2D0e1314e5a921.png&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=8R6PzVqt1PEocauQgZMGXsGz29-nb19M7eqlo1d8EVs&m=7RArAasjvCTVW4mmarg7Pylk--ECPZnZ2DDPqRVsgFM&s=arZFWECPvQhyrPWvpM9bvyxHw6zfFag9vIu74cTCZug&e=> — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_IQSS_dataverse_issues_6086-3Femail-5Fsource-3Dnotifications-26email-5Ftoken-3DAB7P2KVC3JCI3FTUJTV2XZLQEFXHJA5CNFSM4ILBYRF2YY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4HEXIXQQ&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=8R6PzVqt1PEocauQgZMGXsGz29-nb19M7eqlo1d8EVs&m=7RArAasjvCTVW4mmarg7Pylk--ECPZnZ2DDPqRVsgFM&s=ZCK_UKGuczKLX7j-77DnRl9hnwgw8Hw_nC4ZAkREctY&e=>, or mute the thread <https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_notifications_unsubscribe-2Dauth_AB7P2KW66UH5SDSMEUBZ42LQEFXHJANCNFSM4ILBYRFQ&d=DwMFaQ&c=WO-RGvefibhHBZq3fL85hQ&r=8R6PzVqt1PEocauQgZMGXsGz29-nb19M7eqlo1d8EVs&m=7RArAasjvCTVW4mmarg7Pylk--ECPZnZ2DDPqRVsgFM&s=deWfyBAT26vBL-9i7OJQMI_RfCDWig5lodWEHb5lcZA&e=> .

-- Sonia Barbosa Manager of Data Curation, The Dataverse Project Manager of the Murray Research Archive, IQSS Data Science Harvard University All Harvard Dataverse Repository inquiries should be sent to: support@dataverse.harvard.edu All software inquiries should be sent to: support@dataverse.org Need to deposit data? Visit http://dataverse.harvard.edu All test dataverses should be created in our demo environment: https://demo.dataverse.org/ Join our Dataverse Community! https://groups.google.com/forum/#!forum/dataverse-communit <https://groups.google.com/forum/#!forum/dataverse-community>y

[pdurbin]

I gave talk called "Introduction to Dataverse APIs" to the support team for Harvard Dataverse and others who were interested.

Here was the handout I provided, which is simply the table of contents from the "Introduction" page from the API Guide that I re-wrote (in the pull request I intend to create) and a new image explaining what an API is. I didn't have any slides. (Sorry, @shlake, I did see your tweet at https://twitter.com/shlakeuva/status/1161315003342835712 😄 )

The talk emphasized the following points:

• When I originally wrote the API guide, I hadn't considered multiple audiences. The new intro page provides starting points for the following audiences for a given installation such as Harvard Dataverse:
  • Users of Integrations and Apps
  • Power Users (who want to automate depositing "streaming data", for example)
  • Support Teams and Superusers (the primary audience for this talk)
  • Sysadmins
  • In House Developers (not all installations are lucky enough to have these)
• Other API users are not focused on any particular installation of Dataverse:
  • Developers of Integrations, External Tools, and Apps (OJS, OSF, RSpace, DvUploader, etc.)
  • Developers of Dataverse API Client Libraries (pyDataverse, etc.)
  • Developers of Dataverse Itself (me and other full and part time contributors)
• The new "Getting Started" section is intended for researchers and curators and will include common operations such as creating a dataset and uploading files. I could use some help knowing what researchers and curators are often trying to do. Some ideas I picked up from people who came to the talk include:
  • I want to download many files at once.
  • I want to upload many files each with their own description at once.
• The "Lists of Dataverse APIs" write up is new. I recognize that people have had a hard time knowing what's even possible via API. I pointed out the comment at Use OpenAPI standard for Dataverse API's (Swagger) #5794 (comment) that shows that getting a complete list in Swagger format is technically possible in an automated way if we deploy Dataverse to Payara.
• The "Examples" section is just a link to "Getting Started" which is where I plan to put examples. I haven't actually written any examples yet.
• The "Frequently Asked Questions" section is also new. I could use help knowing what questions are frequently asked. One suggestion was knowing what's newly available in APIs so we're thinking we might add an API changelog.
• For support teams and superusers I stubbed out a couple questions under the (existing) "troubleshooting" page in the API Guide. These are the questions we came up with but I don't know what else support teams encounter so suggestions are very welcome:
  • My Dataset Is Locked And Cannot Be Edited or Published
  • Someone Created Spam Datasets and I Need to Delete Them
  • I need to convert my account
  • I want to identify test content (over three years old, for example) and delete it.
• We talked a bit about what's not possible via API. Right now I have a "Tasks That Cannot Be Automated Via API" stub under "getting started" and in some cases, the task can't be done through the GUI either ("unpublish" is an example).
• I recognize that the API Guide is not very consistent. Color coding was suggested so API users know when then need to replace variables with DOIs or whatever. We also talked about how it's unfortunate that many curl commands are so long they scroll off the screen. Maybe this can be fixed with CSS.

For anyone who attended (thanks!) please feel free to add comments here.

I'll get to work on that pull request to get my proposed changes into the API Guide. 😄

[pdurbin]

I recognize that the API Guide is not very consistent. Color coding was suggested so API users know when then need to replace variables with DOIs or whatever. We also talked about how it's unfortunate that many curl commands are so long they scroll off the screen. Maybe this can be fixed with CSS.

I wanted to mention that I'm attempting to fix both problems. Note that in the example below, color highlighting has been added for variables and long lines wrap across multiple lines:

[pdurbin]

I just created pull request #6107 and I'd love feedback. I'm happy to add on to it.