Project

General

Profile

Webservices en API

Op deze pagina zijn het ontwerp en implementatie van de application programming interface (API) en het bijbehorende gegevensstructuren, protocollen, etc. van de OpenTaal webservices gedocumenteerd.

Aanpak

Incrementeel zal hier het ontwerp en implementatie worden besproken. Momenteel is de insteek klein te beginnen maar wel vooruit te blijven denken om met maximale herbruikbaarheid nieuwe webservices te ontwikkelen. In verband met internationaal gebruik zullen de namen in de API zo veel mogelijk in het Engels zijn. Alles met ??? verdient correct ingevuld te worden.

Vraag, moeten output variabelen altijd aanwezig zijn om bij afwezigheid NULL in de database te represteren t.o.v. een lege string in de database???

Gebruik van JSON en REST???

Security

De webservices zullen zich moeten beschermen tegen misbruik.

API-sleutel

Iedereen (ook intern) die gebruik wil maken van de OpenTaal webservices dient zich te identificeren met een API-sleutel. Hiermee kunnen alleen geregistreede gebruikers de webserviceaanroepen en gebruikers die de voorwaarden niet respecteren (tijdelijk) worden geblokkeerd.

Het registratieproces zal niet geautomatiseerd zijn en zal gemiddels ? werkdagen duren voordat een partij een API-sleutel ontvangt. Deze API-sleutel is een uniek per gebruiker en werkt voor aanroepen vanaf een bepaalde fully qualified domain name die tijdens de registratieoprocedure is opgenomen. Wijzigen van de fully qualified domain name die bij een API-sleutel hoord duurt ? werkdagen waarna voor ??? werkdagen de oude fully qualified domain name ook nog zal werken.

Throtling

Per API key zal er aan throtling gedaan moeten worden om (bedoelde of onbedoelde) overbelasting van de server te voorkomen. De meest eenvoudige implementatie is om niet meer dan ??? API-aanroepen per API-sleutel per miliseconden toe te laten.

Data structure: versions

key-value dictionary:

name type examples
key char??? 1_00, 1_10G, 2_00, 2_10, next_version
value char ???

Service: api.opentaal.org/word_details

Word details for a single word.

I/O required type name default comment
input yes char??? api_key
input no char75 word 'woorddetails' default can be used as test, may not contain regular expressions
output no key-value dictonary versions
output no char??? comments
output no char75 alternative

Moet deze eigenlijk niet generieker zijn net als de volgende en ook regex accepteren en meerdere woorddetails kunnen teruggeven??? Kunnen we er altijd nog kiezen om regex uit te schakelen en daardoor output tot maar een woord te beperken.

Service: api.opentaal.org/harvested_sentence

Harvested sentences containing a phrase.

I/O required type name default comment
input yes char??? api_key
input no char75 phrase 'Stichting OpenTaal' default can be used as test, may contain regular expressions
output no list of char??? sentences