add beginner friendly API documentation #6086

[pdurbin]

• Closes Beginner friendly API documentation #6086 (Beginner friendly API documentation)
• Also closes Is that possible to add an another example for downloading file with curl? #3319 (Is that possible to add an another example for downloading file with curl?)
• Also closes correct docs for api/dataverses/$id/metadatablocks API endpoint #3624 correct docs for api/dataverses/$id/metadatablocks API endpoint

---

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

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:
  • SWORD API documentation cleanup SWORD API documentation cleanup #3588
  • curl issue with native API curl issue with native API #4510
  • native API for creating dataverse reports parse error for valid json native API for creating dataverse reports parse error for valid json #3533
  • doi, "start" parameter using the Search API doi, "start" parameter using the Search API  #4377
• 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]

Can one of the admins verify this patch?

[coveralls]

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

[mheppler]

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. 👍

[mheppler]

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

[pdurbin]

@mheppler thanks for fixing those typos!

[donsizemore]

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.

[donsizemore]

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

[donsizemore]

s/server/Dataverse instance/g ?

[donsizemore]

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