Document - Make use of MyData API "official"

[shlake]

The MyData API works !! but is undocumented (not in any guides) and not integrated into the Dataverse tests.

The MyData API is a good option for getting a list of just the datasets & dataverses an authenticated user can edit. Per Phil, here's the scope of what needs to be done:

• Document in the API Guide how to use the My Data API.
• Write integration tests for the My Data API so that it is exercised regularly.

[pdurbin]

We mentioned this issue while discussing #5351 (comment) and the question was asked, "What does the output of the MyData API look like?"

Below is an example from @shlake (thanks!) from https://groups.google.com/d/msg/dataverse-community/jZRBVGpNLcg/HxfJC-HyAwAJ

curl -s "https://demo.dataverse.org/api/mydata/retrieve?key=$API_TOKEN&role_ids=6&dvobject_types=Dataset&published_states=Published&published_states=Unpublished&published_states=Draft&published_states=In+Review&published_states=Deaccessioned" | jq .

{
  "success": true,
  "data": {
    "pagination": {
      "isNecessary": false,
      "numResults": 1,
      "numResultsString": "1",
      "docsPerPage": 10,
      "selectedPageNumber": 1,
      "pageCount": 1,
      "hasPreviousPageNumber": false,
      "previousPageNumber": 1,
      "hasNextPageNumber": false,
      "nextPageNumber": 1,
      "startCardNumber": 1,
      "endCardNumber": 1,
      "startCardNumberString": "1",
      "endCardNumberString": "1",
      "remainingCards": 0,
      "numberNextResults": 0,
      "pageNumberList": [
        1
      ]
    },
    "items": [
      {
        "name": "accent",
        "type": "dataset",
        "url": "https://doi.org/10.5072/FK2/BH7BFD",
        "global_id": "doi:10.5072/FK2/BH7BFD",
        "description": "Tabular data with a header column containing an accent.",
        "published_at": "2017-04-11T13:12:22Z",
        "citationHtml": "Durbin, Philip, 2017, \"accent\", <a href=\"https://doi.org/10.5072/FK2/BH7BFD\" target=\"_blank\">https://doi.org/10.5072/FK2/BH7BFD</a>, Demo Dataverse, V1, UNF:6:cZCHfUt6X5GE62EWlVI/Pw== [fileUNF]",
        "citation": "Durbin, Philip, 2017, \"accent\", https://doi.org/10.5072/FK2/BH7BFD, Demo Dataverse, V1, UNF:6:cZCHfUt6X5GE62EWlVI/Pw== [fileUNF]",
        "matches": [],
        "score": 1,
        "entity_id": 15695,
        "api_url": "https://demo.dataverse.org/api/datasets/15695",
        "authors": [
          "Durbin, Philip"
        ],
        "publication_statuses": [
          "Published"
        ],
        "is_draft_state": false,
        "is_in_review_state": false,
        "is_unpublished_state": false,
        "is_published": true,
        "is_deaccesioned": false,
        "date_to_display_on_card": "Apr 11, 2017",
        "parentId": "1230",
        "parentName": "Philip Durbin Dataverse",
        "parent_alias": "pdurbin",
        "user_roles": [
          "Admin",
          "Contributor"
        ]
      }
    ],
    "total_count": 1,
    "start": 0,
    "search_term": "*:*",
    "dvobject_counts": {
      "dataverses_count": 0,
      "files_count": 0,
      "datasets_count": 1
    },
    "pubstatus_counts": {
      "unpublished_count": 0,
      "draft_count": 0,
      "published_count": 1,
      "deaccessioned_count": 0,
      "in_review_count": 0
    },
    "selected_filters": {
      "publication_statuses": [
        "Published",
        "Unpublished",
        "Draft",
        "In Review",
        "Deaccessioned"
      ],
      "role_names": [
        "Contributor"
      ]
    }
  }
}

[pdurbin]

I just wanted to mention that yesterday in IRC ( http://irclog.iq.harvard.edu/dataverse/2019-02-05#i_86514 ) someone asked how to use the MyData API, specifically, if it's possible to search. In this case it sounds like the Search API could have been used if the Search API supported unpublished datasets.

[pdurbin]

I was just showing @sekmiller #5794 (comment) and I'd feel remiss if I didn't add a note here (and the screenshot below) explaining that we get a comprehensive dump of all the Dataverse APIs "for free" from Swagger/OpenAPI when we follow the procedure in that comment (which is just a proof of concept). For example, here's the dump from the MyData API:

This doesn't speak to whether the MyData API is official or not ("bona fide" as they say in O Brother, Where Art Thou). But once we upgrade to Payara it will be easier to pull API information out of Dataverse programmatically, which is a beautiful thing! 🎉

[sirineREKIK]

Pull Request: #9596

[shlake]

YAY!!! Just saw this as I was reading the release notes for V5.14!!