Native API: publish dataset endpoint mismatch (POST vs. GET) in docs vs. code

[pdurbin]

http://guides.dataverse.org/en/4.1/api/native-api.html#datasets says...

Publishes the dataset whose id is passed. The new dataset version number is determined by the most recent version number and the type parameter. Passing type=minor increases the minor version number (2.3 is updated to 2.4). Passing type=major increases the major version number (2.3 is updated to 3.0):

POST http://$SERVER/api/datasets/$id/actions/:publish?type=$type&key=$apiKey

... but the method actually takes a GET rather than a POST:

curl -X GET -H "X-Dataverse-key:$API_TOKEN" http://localhost:8080/api/datasets/2675227/actions/:publish?type=minor

Probably it should be a POST, as documented, since we're changing state on the server. Yes, this will break backward compatibility of the Native API but I think it's worth it.

I'll set this issue for the current milestone for now and pass to @scolapasta for assignment.

[bencomp]

What was the result/status of investigating tools like Enunciate for generating REST API documentation based on Javadoc? I love documentation (and cannot link #775 enough ;)), but in situations like these I'd think no mismatch between code and documentation would have existed.

[pdurbin]

Huh. Enunciate wasn't really on my radar but I see you did mention it at http://irclog.iq.harvard.edu/dataverse/2015-01-07#i_15039 . (I was thinking more of Swagger back then.) I do love me some documentation.

As a first step, it might be interesting to at least compare Enunciate output to our docs as a sanity check. Of course, more integration tests would probably also find mismatches like this. (I'm actually working on writing more right now, which is how I found it.)

[pdurbin]

Fixed in pull request #3550. Passing to Code Review at https://waffle.io/IQSS/dataverse

[kcondon]

Now supports POST in addition to GET (so as not to break existing implementations).
Closing