Avoimen rajapinnan dokumentaatio määritelmässä

[Mygee]

Avaan nyt keskustelun määritelmän vaatimasta avoimen rajapinnan dokumentaatiosta.
Yleisesti dokumentaation puute on suurin este rajapintojen hyödyntämiseen. Esimerkiksi koodiesimerkkien puute on todellinen ongelma rajapinnan hyödyntämisessä.

[aapris]

Olen samaa mieltä ja jokaisesta rajapinnasta pitäisi olla vähintään komentoriviesimerkkejä (esim. curl- tai httpie-ohjelmalla tai vastaavalla) sekä ainakin 1-2 eri ohjelmointikielellä (esim. java, html+javascript, node.js, python) tehdyt esimerkit, joilla dataa saa pyydettyä rajapinnasta ja käsiteltyä sitä jollain tavoin. Aina parempi, jos rajapinnan tarjoajalla olisi tarjota myös jonkinlainen SDK (softamoduuli/kirjasto), jolla pääsee helposti ja nopeasti käyttämään rajapintaa.