Review Native API Documentation

[posixeleni]

From @pdurbin #1489 (comment)

Putting "all native APIs" on a single page at http://guides.dataverse.org/en/latest/api/native-api.html feels wrong since there are so many endpoints there.

Are we saying that creating a dataset with JSON is an advanced operation?

[bencomp]

Suggestion for Native API documentation: data samples for every endpoint that include a note saying which parameters are required, optional and ignored. I currently have to go into the code to find what fields are required or ignored.

(Edited to clarify "level of requiredness")

[pdurbin]

@bmckinney is playing with Swagger (i.e. @ApiOperation) here, for example: https://github.com/bmckinney/bio-dataverse/blob/8a7403b5cfccb02c913168f89825fbd5615af326/src/main/java/edu/harvard/iq/dataverse/batch/launcher/ImportLauncher.java#L57

He gave me a demo yesterday and it looks really nice.

[pdurbin]

I was telling @pameyer today that at the very least, the native API docs should have descriptions of the various endpoints at the top of the page like SWORD does:

Without these headings, it quite hard to find stuff.

In addition, the native API docs should be split into multiple pages. That's why I put the Search API on it's own page. It's overwhelming to have so much on one page, especially if we provide more JSON examples, which we should.

[pdurbin]

Related: #3624

[pameyer]

Error message can sometimes be clearer:

• API for creating datasets fails: Error parsing the POSTed json into a dataverse: Field alias is mandatory #3805 : missing dataverse alias in URL reported as a problem with JSON

[RightInTwo]

Are there any developments in regards to a Swagger/OpenAPI definition (or similar) for the Native API?

[pdurbin]

@RightInTwo nope. As I said above on April 1st, 2016, one of us played with adding Java annotations (@ApiOperation) to automatically generate Swagger output (this was not an April Fool's joke), but nothing has been done since then.

We are definitely open to pull requests!

The main thing I want for this issue is not necessarily Swagger but to split the long "native" API into multiple pages, one for "Dataverses", one for "Datasets", one for "Admin", etc. We should also have a "greatest hits" or FAQ of common operations such as:

• how to create a dataset
• how to upload a file

As of http://guides.dataverse.org/en/4.11/api/native-api.html here's how many operations are on that one page:

[pdurbin]

Are there any developments in regards to a Swagger/OpenAPI definition (or similar) for the Native API?

@RightInTwo these days there's an issue to track: Use OpenAPI standard for Dataverse API's (Swagger) #5794

And there is a development in the sense that we learned that if we upgrade from Glassfish 4 to Payara 5, we can get Swagger/OpenAPI compatible output automatically. Please see #5794 (comment) and #5155 (comment)

I mentioned this in pull request #6107, which I made yesterday. Since that pull request was about making the API Guide better, I'm going to go ahead and close this issue.

Anyone reading this is welcome to open new issues about how to improve the API Guide. Also, pull request #6107 hasn't been merged yet and feedback is welcome!