Het is met zeker genoegen én enige trots dat ik [eindelijk] de netjes API mag voorstellen. Met de API kan je, eenvoudig gezegd, je eigen toepassingen ontwikkelen die gebruik maken van de inhoud op netjes.

Getracht is zoveel mogelijk van die inhoud toegankelijk te maken (zelfs inhoud die je anders niet bekijken kan) en ik hoop heel eerlijk dat de API een token mag zijn van de kwaliteit en oprechtheid waarmee netjes gepaard wil gaan. Zijnde een social news site voor Vlaanderen en Nederland, no strings attached. (Op het internet van de lage landen is het nu eenmaal een kwestie van vertrouwen winnen, niet?)

Gebruik van de API is helemaal gratis en toegankelijk voor iedereen. Je hoeft dus geen account te hebben om te kunnen klooien.

Ik tracht in de loop van de volgende week een volwaardige doc te kunnen delen maar in tussentijd, én voor de techneuten onder ons, alvast deze:
(Of skip meteen naar de voorbeelden onderaan dit artikel)

Response Types
Zijn XML en PHP (Serialized.) Kent geen default. Geen response type meegeven levert momenteel een vette 404 op! Dat gezegd hebbende…

Error Codes
Zijn er nog niet.

Application Key (apikey)
Is een argument en dient je toepassing of web site eenvoudigweg te bekend maken. Een e-mail adres of URL is voldoende.

End Points
Quasi elke toegankelijke URI op netjes werkt als end point in de API. Een uniek item wordt aangeroepen als /netjes/item/{item_id}/ en een uniek domein als /netjes/domein/{www.domein.be}/. Ook én exclusief beschikbaar in de API zijn de end points /netjes/ en /njetjes/ die de “netjes” en “njetjes” of positieve en negatieve (jaaa) rateringen weerkeren.
Deze end points zijn momenteel actief:
/nieuw
/in_spe
/populair (en /populair/vandaag, /populair/week enz.)
/{onderwerp_gebruik_naam} (en /{onderwerp_gebruik_naam}/in_spe, /{onderwerp_gebruik_naam}/vandaag, /{onderwerp_gebruik_naam}/week enz.)
/{een van bovenstaande end points}/netjes
/{een van bovenstaande end points}/njetjes
/netjes/gebruikers
/netjes/gebruikers/{gebruiker_gebruik_naam}
/netjes/gebruikers/{gebruiker_gebruik_naam}/netjes
/netjes/gebruikers/{gebruiker_gebruik_naam}/toegevoegd
/netjes/gebruikers/{gebruiker_gebruik_naam}/gereageerd
/netjes/item/{item_id}
/netjes/item/{item_id}/netjes (en /netjes/item/{item_id},{item_id},{item_id}, …/netjes)
/netjes/item/{item_id}/njetjes (en /netjes/item/{item_id},{item_id},{item_id}, …/njetjes)
/netjes/domein/{www.domein.be}
/netjes/domein/{www.domein.be}/netjes
/netjes/domein/{www.domein.be}/njetjes

Argumenten
Met uitzondering van end points waar één enkele waarde wordt teruggekeerd (zoals /netjes/item/{item_id}/ of /netjes/gebruikers/{gebruiker_gebruik_naam}/ zijn volgende argumenten van toepassing:
vanaf - Default op 0. Verzet de interne teller in een resultatenset.
aantal - Default op 20. Nog geen limiet. Geeft de opgegeven waarde als aantal resultaten weer.
sorteer - Bij items zijn de sorteer opties momenteel: populair_desc, populair_asc, toegevoegd_desc, toegevoegd_asc. Bij gebruikers zijn dat: naam_asc, naam_desc, geregistreerd_asc en geregistreerd_desc. Bij netjes en njetjes zijn enkel toegevoegd_asc en toegevoegd_desc beschikbaar.

Beperkingen
Zijn er evenmin. Wellicht zal over verloop van tijd het argument aantal een beperking krijgen. Voor nu kan ik maar verzoeken beleefd te zijn en de server niet te verdrinken in requests.

Requests in de praktijk
/nieuw/
/marketing/in_spe/
/apple/in_spe/netjes/?sorteer=toegevoegd_desc
/netjes/gebruikers/sans/
/netjes/item/444/
/netjes/item/360/netjes/?sorteer=toegevoegd_asc
/netjes/domein/www.demorgen.be/?sorteer=populair_desc&aantal=10
/netjes/domein/www.demorgen.be/netjes/
(Alle voorbeelden wijzen naar de XML response type.)

Wat volgt nog?
Gebruiker_id als end point, een timestamp filter (van… tot…), item_titel_gebruik als end point én error codes.

En dat is het in een notedop. Zoals ik al vermeldde hoop ik de doc met beschrijving van alle end points en arguments klaar te hebben in de loop van volgende week (en heel wellicht de overige end points en errors ook.) Maar voor wie besluit zich reeds aan een mashup te wagen is heel welkom me te e-mailen voor support en advies. Anderzijds is er ook een netjes forum op Google Groups.

En omdat een API niet gelaunched kan worden zonder minstens één functioneel voorbeeld: netjes nieuw! (met broncode.)