search

noi-techpark / odh-docs

Open Data Hub (http://opendatahub.com/) Documentation
http://opendatahub.readthedocs.io/en/latest/index.html
3 stars 4 forks source link

Issue 147 description of new API v2 #151

Closed stefanodavid closed 4 years ago

stefanodavid commented 4 years ago

@Piiit I must say I disagree with many of your remarks. I'll apply the changes you require anyway, and add my comments for the record.

Piiit commented 4 years ago

@Piiit I must say I disagree with many of your remarks. I'll apply the changes you require anyway, and add my comments for the record.

I am not sure, but maybe you are talking about the removal of additional tools like jq?

If so, I think the less is more and we should really just focus solely on the API and not tools around. If you think that those tools could be useful, then we could add another chapter for them, like some special tricks&tips for developers. What do you think?

stefanodavid commented 4 years ago

I am not sure, but maybe you are talking about the removal of additional tools like jq?

Well, jq is an open source CLI tool and is mentioned in the Open Data Hub documentation since more than one year and in this case with the sole purpose of beautyfing the output of the API call. Do you think that someone who tries the API by copy&paste--without knowing JSON or how to parse it--would find more readable this:

$ curl -X GET "https://mobility.api.opendatahub.bz.it/v2/tree" -H "accept: application/json" [{"id":"Bicycle","description":null,"self":{"stations+datatypes":"https://mobility.api.opendatahub.bz.it/v2/tree/Bicycle/*","stations+datatypes+measurements":"https://mobility.api.opendatahub.bz.it/v2/tree/Bicycle/*/latest","stations":"https://mobility.api.opendatahub.bz.it/v2/tree/Bicycle"}},{"id":"Bicyclestationbay","description":null,"self":{"stations+datatypes":"https://mobility.api.opendatahub.bz.it/v2/tree/Bicyclestationbay/*","stations+datatypes+measurements":"https://mobility.api.opendatahub.bz.it/v2/tree/Bicyclestationbay/*/latest","stations":"https://mobility.api.opendatahub.bz.it/v2/tree/Bicyclestationbay"}},{"id":"BikesharingStation","description":null,"self":{"stations+datatypes":"https://mobility.api.opendatahub.bz.it/v2/tree/BikesharingStation/*","stations+datatypes+measurements":"https://mobility.api.opendatahub.bz.it/v2/tree/BikesharingStation/*/latest","stations":"https://mobility.api.opendatahub.bz.it/v2/tree/BikesharingStation"}},{"id":"BluetoothStation","description":null,"self":{"stations+datatypes":"https://mobility.api.opendatahub.bz.it/v2/tree/BluetoothStation/*","stations+datatypes+measurements":"https://mobility.api.opendatahub.bz.it/v2/tree/Blu

So, yes, I do think that mentioning such a tool is an added value to the documentation. But I' have removed it according to your request.

The same reasoning applies to the mention of the JSON plugin. Ask a casual user to open the browser without a JSON plugin and ask him what he thinks of what he sees...

If so, I think the less is more and we should really just focus solely on the API and not tools around. If you think that those tools could be useful, then we could add another chapter for them, like some special tricks&tips for developers. What do you think?

I think that someone who receives the above aoutput would never give the Open Data Hub a go. Besides, if we should focus only on the API and not on tool, why in the tourism domain there are several inline mentions of a closed source software like Postman? :-) Will you open an issue to get rid of them as well?

Piiit commented 4 years ago

@stefanodavid I never said that we should remove them completely, just that we should in the API chapter focus solely on the API and make another chapter to talk about such tools, because otherwise we mix API descriptions and tool descriptions

But maybe that is just my opinion: @mrabans @ohnewein @bertolla @RudiThoeni What do you think about it? TL;DR... we discuss to just explain API calls in the api description chapter, and not talk about browser plugins, CLI tools and other graphical tools to make http calls and show JSON output in a nice way. I think, the API description should be concise and just the API itself, then in another chapter we could probably explain such tools. Stefano thinks it is better to have both in the same chapter together, as we had them already for some time. I do not want to make this decision alone, so what is your opinion on that regard?

Piiit commented 4 years ago

@stefanodavid Example of an API description, that is very nice IMO... http://postgrest.org/en/v7.0.0/api.html

Just as idea, as how I like it... and here we do not have a single external tool

stefanodavid commented 4 years ago

@stefanodavid Example of an API description, that is very nice IMO... http://postgrest.org/en/v7.0.0/api.html

Just as idea, as how I like it... and here we do not have a single external tool

My point is that this is no API description, but an howto called How to Access Mobility Data With API v2 and is intended for all users, not for hardcore developers...

But anyway, I implemented all the changes you asked for, let's stop this useless discussion. As I already wrote here, I disagree with most of your comment, but this is not important. I won't discuss your feedback anymore, so I stop wasting time and can focus on other more important tasks.

If you require additional changes, please do so, otherwise merge the PR, thanks.