Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add beginner friendly API documentation #6086 #6107

Merged
merged 7 commits into from
Aug 23, 2019
Merged

Conversation

pdurbin
Copy link
Member

@pdurbin pdurbin commented Aug 20, 2019


To give feedback on this pull request, you are welcome to look at the following build of the guides:

http://guides.dataverse.org/en/6086-api-guide/api/intro.html

Here's a screenshot of the re-written "intro" page as of 39cd360

Screen Shot 2019-08-20 at 3 22 57 PM

Update for 2019-08-20:

  • After standup we discussed the scope of this issue. I showed a longish list of related issues but we decided only to add "closes" for the issues above. For the record, here are the open issues I was considering tackling to some degree or another:
  • We also discussed two use cases from @sbarbosadataverse that came out of my API talk. I chatted with her afterwards and she plans to make issues for them:
    • I want to download many files at once.
    • I want to upload many files each with their own description at once.
  • Also on the screen from my todo list was feedback from the community:
    • document DatasetThumbnail API
    • add section on undocumented APIs? See Document - Make use of MyData API “official” Document - Make use of MyData API "official" #5042
    • one thing, that i asked myself: is it mandatory to add the typeClass and multiple attributes to the Dataset JSON?
    • and which attributes are required in the JSON file, for Dataverse, Dataset and Datafile.
    • and: which fields can only have one value, and which can have multiple (arrays)?
  • In short, there's agreement that the pull request improves the API Guide but we need to "trim the tail" and save the work above for another day. Pull requests welcome! I'd also like to highlight that @donsizemore mentioned that a graduate student might be able to help with documentation: update Native API examples #6083 which is about moving to full curl examples, especially for POST commands where you need to send JSON or whatever. I hope people like the way I'm documenting things now in the files I touched, with Bash export commands for environment variables used in curl commands. Now color coded! Now with lines that wrap! 😄
  • Oh, I also asked for feedback from the community at https://groups.google.com/d/msg/dataverse-community/V5WkMGDS4VI/PLzPUVvoFwAJ

@dataversebot
Copy link

Can one of the admins verify this patch?

@coveralls
Copy link

coveralls commented Aug 20, 2019

Coverage Status

Coverage decreased (-0.002%) to 19.482% when pulling 3878a56 on 6086-api-guide into d6a81a9 on develop.

@pdurbin pdurbin requested review from shlake and donsizemore August 20, 2019 19:23
Copy link
Contributor

@mheppler mheppler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this was demo in front of a live audience, I trust the content is sound and the code examples accurate. Focused review on formatting and other minor details like typo's. Will spare @pdurbin from fixing those. Approving and quickly following up with commit resolve any and all typos. Overall a great improvement to our guides. 👍

doc/sphinx-guides/source/api/intro.rst Outdated Show resolved Hide resolved
doc/sphinx-guides/source/api/intro.rst Outdated Show resolved Hide resolved
doc/sphinx-guides/source/api/intro.rst Outdated Show resolved Hide resolved
doc/sphinx-guides/source/api/intro.rst Outdated Show resolved Hide resolved
doc/sphinx-guides/source/api/getting-started.rst Outdated Show resolved Hide resolved
doc/sphinx-guides/source/api/getting-started.rst Outdated Show resolved Hide resolved
doc/sphinx-guides/source/api/faq.rst Outdated Show resolved Hide resolved
doc/sphinx-guides/source/api/auth.rst Outdated Show resolved Hide resolved
@mheppler
Copy link
Contributor

Fixed typo's and other small details as promised. Ready for QA.

@mheppler mheppler removed their assignment Aug 23, 2019
@kcondon kcondon merged commit 0c9a229 into develop Aug 23, 2019
@kcondon kcondon deleted the 6086-api-guide branch August 23, 2019 21:51
@kcondon kcondon self-assigned this Aug 23, 2019
@pdurbin
Copy link
Member Author

pdurbin commented Aug 23, 2019

@mheppler thanks for fixing those typos!

@djbrooke djbrooke added this to the 4.16 milestone Aug 27, 2019

See the :doc:`/api/intro` section of the API Guide for a high level overview of Dataverse APIs. Below are listed problems that support teams might encounter that can be handled via API (sometimes only via API).

A Dataset Is Locked And Cannot Be Edited or Published
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be helpful to point out that one should be certain Dataverse is finished with a dataset (worst case: stop glassfish) before removing the lock.


Depending on how open your installation of Dataverse is to the general public creating datasets, you may sometimes need to deal with spam datasets.

Look for "destroy" in the :doc:`/api/native-api` section of the API Guide.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Point out that unpublished datasets may be deleted via http://guides.dataverse.org/en/latest/api/native-api.html#delete-unpublished-dataset ?

How to Get an API Token
-----------------------

Your API token is unique to the server you are using. You cannot take your API token from one server and use it on another server.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/server/Dataverse instance/g ?

How Your API Token Is Like a Password
-------------------------------------

Anyone who has your API Token can add and delete data as you so you should treat it with the same care as a password.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... add and delete data with your credentials, so you should ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
7 participants