Home

API - versie 1.0

Na een lange tijd gewacht te hebben, brengen we de eerste versie van onze API uit.

Wat is een API, en wat kan ik er mee?
Met de API kan je communiceren vanuit (web)applicaties. Je kunt dus informatie opvragen en deze op een eenduidige manier terug krijgen. Geen HTML of Javascript meer misbruiken, maar je data via een eenvoudige GET van onze API opvragen. Je krijgt vervolgens een XML resultaat terug met je gewenste gegevens.

De functies:
GetShowById
Hiermee krijg je van alles terug van de serie:

De naam
De directlink naar die serie op Bierdopje
Aantal seizoenen, afleveringen
Genre, Status en meer.

De enige variabele die deze functie ondersteund is een integer van de serieID zoals deze op Bierdopje gebruikt wordt. Dit is dus niet het TVDB id.

GetShowByTVDBID
Deze functie is vrijwel identiek aan GetShowById, alleen kan je hier de TVDB idnummering gebruiken om gegevens op te vragen.

FindShowByName
Zoek je hier op een serienaam (of een deel ervan), krijg je gegevens terug. De gegevens die je krijgt zijn gelijk aan GetShowById en GetShowByTVDBID.

Als je de show ID weet, is het wel aan te raden om de GetShowById functie te gebruiken, omdat deze sneller klaar is met ophalen en presenteren van gegevens.

GetAllEpisodesForShow
Je kunt alle afleveringen van een serie (met BD-ID) opvragen. Je krijgt dan o.a. terug:

EpisodeID - BD
EpisodeID - TVDB
Titel
Airdate
Directlink naar aflevering @ BD
Of er een WIP is, hoever deze is en wie er mee bezig is
Of er subs zijn
Summary, votes, etc.

GetEpisodeById
Deze functie geeft informatie terug van Ã©Ã©n enkele aflevering ,te specificeren met het afleveringsID welke je terugkrijgt uit "GetAllEpisodesForShow". Bevat dezelfde info, maar is sneller klaar omdat het maar Ã©Ã©n record op hoeft te halen.

GetAllSubsForEpisode
Je kunt met deze functie + het afleveringsnummer kijken of er subs (zowel EN als NL) beschikbaar zijn, als dit het geval is krijg je daar wat info over terug zoals: filename, uploader, aantal downloads, aantal reacties, datum.

Gebruik van API
Om de API te gebruiken heb je een API key nodig. Per applicatie waarin dit gebruikt wordt, zal je een API key aan moeten vragen. Dit kan je doen vanuit je "Instellingen" scherm en dan te kiezen voor API.

Je krijgt je key meteen toegewezen, en deze is direct actief.

Statistieken
Voor statistieken houden we bij hoe vaak je de API aanroept. We kunnen we je API key(s) blokkeren als we merken dat deze misbruikt worden.

Structuur
De API is momenteel erg beta. We hebben hem wel enigszins getest, maar het uiteindelijke testen is voor de eindgebruikers.

De structuur zoals deze is zal zo blijven, er komen hooguit meer functies en "items" erbij. Mocht er onverhoopt iets wijzigen aan de bestaande functies/items binnen deze functies zullen we je dit laten weten.

Caching
De API wordt voor -momenteel- voor 20 minuten gecached om het laden zo optimaal mogelijk te houden. Je ziet in je resultaten of het uit de cache komt of niet. Elke eerste request is trager dan de opvolgende, aangezien deze de data vers voor je uit de database haalt en ze vervolgens cached.

Fair Use Policy
Aan het gebruik van de API zit een "Fair Use Policy" gekoppeld. Als je deze overschrijd, heb je kans dat we je API key (tijdelijk) suspenden.

Op dit moment zit er nog geen "rate limiting" in, we gaan de komende weken kijken of dit noodzakelijk is en bouwen dit in als dat noodzakelijk blijkt.

Standaard classes/functies
In de toekomst zal er onverhoopt een standaardpakket te verkrijgen zijn waarmee je nog sneller van start kunt gaan. Hierbij valt te denken aan een PHP class of een andere willekeurige taal.

Schrijf API
We gaan de komende periode deze API in de gaten houden. Als blijkt dat er voldoende gebruik van gemaakt word, zullen we verder gaan met de volgende fase: Schrijf api.

Deze API bied de mogelijkheid om zaken te toe te voegen/wijzigen aan de website. Ook vallen hier "user focussed" zaken onder. Je kunt denken aan het ophalen van je favoriete series, je time wasted, maar ook bijvoorbeeld het toevoegen van een serie aan je favorieten via een andere applicatie/website dan de onze.

Of deze api daadwerkelijk komt is afhankelijk van een hoop factoren, aangezien onze focus voornamelijk op de functies ligt die het merendeel (dagelijks) gebruikt.

Ondersteuning
Ondersteuning van deze api geschied via IRC (tabje "Chat" op de website) of via het Developer forum. PM's over de API worden niet gelezen of beantwoord.

Nu de API live is, kan je onder "Instellingen" je API key aanvragen.

Nadat je je key hebt, kan je de API gebruiken via:

http://www.bierdopje.com/api/APIKEY
http://api.bierdopje.com/APIKEY waarbij je API key vervangt door die je hebt gekregen. Vervolgens krijg je - als je geen commando opgeeft - algemene info en gebruikinfo te zien.

Sypher wijzigde dit bericht op 03-01-2010 om 19:00, totaal 2 keer bewerkt

Let op: We verwachten dat je applicatie zich sociaal gedraagt.
Zie ook het volgende topic voor meer informatie:Aanscherping controle API gebruik*

Home

BierdopjeV3 Alpha nu beschikbaar. Wil je helpen? Kijk dan hier

API - Versie 1