search

noi-techpark / bdp-core

Open Data Hub / Timeseries Core
https://opendatahub.com
Other
9 stars 4 forks source link

EPIC: As an app developer, I want a well documented API to be able to use it in my app. #19

Open ohnewein opened 6 years ago

ohnewein commented 6 years ago

In order to ease the deployment of applications on top of ODH's code and datasets, annotations to the Web Services should be added to the REST API using swagger. The following list shows which APIs have already swagger annotations added ["unique name" has been used - see geobank-dataset spreadsheet]:

stefanodavid commented 6 years ago

Done so far for the mobility domain (and therefore for all open datasets), bar a few open questions. I plan however to add a page in the docs with the descriptions of some of the outcomes, to avoid flooding the swagger interface. What do you think @ohnewein ?

@RudiThoeni what about the tourism domain? You said you already have them

ohnewein commented 6 years ago

Hi @stefanodavid , I think the documentation is getting very useful! In the section http://opendatahub.readthedocs.io/en/latest/domains.html#domains-with-available-datasets the developer gets an overview of APIs and the links to the documentation for each of them. What could be improved, maybe directly in the header section of the single swagger pages, is a description of the data provided. At the moment only who knows the data already, will understand what meant under it.bz.geobank.bluetooth and similar terms. A short description would be useful.

stefanodavid commented 6 years ago

@ohnewein Yes, this was my next step: documenting the data model of the API responses. However, I did not yet found a way to do it directly in swagger and I was planning to add a page (or more, depending on the complexity of the response) to the doc to document it. Perhaps not the best solution, but probably the quickest. What do you think?

About the page you linked, the description is already pushed in the repo, but not yet online, since I'm planning to built it this evening.

RudiThoeni commented 6 years ago

I have seen you linked the tourism data sets currently available

  1. it.bz.geobank.activity_poi is a collection of activities and points of interest in the South Tyrol region. Data have been extracted from different sources. http://service.suedtirol.info/swagger/ui/index#/ODHActivityPoi
    Here we have to give the information that currently without credentials only data from the south tyrolean museums are available, because it is the only free available dataset at the moment
  2. it.bz.siag.museum provides information about South Tyrolean museums. http://service.suedtirol.info/swagger/ui/index#/ODHActivityPoi

This endpoint means the data directly from siag, i found a documentation in the open data portal from the province, link http://daten.buergernetz.bz.it/de/dataset/musei-in-alto-adige Here we have to link with this doc

stefanodavid commented 6 years ago

Hi @RudiThoeni I added a few information about both datasets, but about the it.bz.siag.museum one I was able to just download the dataset, there seem to be no API for it. Do you know if there's any swagger-like endpoint for this dataset?

RudiThoeni commented 6 years ago

There is no swagger only two endpoints. But this doesn't matter because this is a third party service and has to be only mentioned with basic infos in our list......

as far as i know the api is this (xml soap service) https://cert.provinz.bz.it/musport/services/MuseumsService.MuseumsServiceHttpSoap11Endpoint/getMuseums (json service) http://daten.buergernetz.bz.it/services/musport/v1/geojson

stefanodavid commented 6 years ago

thanks @RudiThoeni I think I already conveyed these information in the docs: http://opendatahub.readthedocs.io/en/latest/datasets.html#museum-dataset

Would you agree or should I add some more details?

stefanodavid commented 5 years ago

After a discussion with @bertolla yesterday, we are going to have more detailed, dataset-dependent annotations for the v2 API. This will mean also a cleaner repo, in which code and annotations are separated.

stefanodavid commented 4 years ago

@bertolla @ohnewein, I think this can be closed now, or, since I am not writing the annotations anymore, reassign the issue.