nrk.no

Korleis NRKs API burde fungere

Kategorier: Internett, Kommentar, Nettjenester & NRK


Verktøy
Den engelske avisa The Guardian lanserte i dag «Open Platform«, ein API som gjev «alle» tilgang til store deler av avisas innhold via eit enkelt HTTP-grensesnitt.

Kvifor er dette viktig?

NRK, VG, Dagbladet og alle andre større nyheitsorganisasjoner sit på enorme mengder data. Ved å tilgjengeleggjere desse dataene via ein API sørger ein for at innholdet får lengre rekkevidde. Du kan hente innhold frå fleire kjelder rundt om på nettet, og sy dei saman i den konteksten som passar for deg.

NRK planlegg, som du har lest tidligare, å utvikle API for sine tenester.
Sidan dette prosjektet fortsatt er i planleggingsfasen tenkte eg at litt innspel frå ein ekstern utviklar (…og forhåpentligvis fleire andre i kommentarfeltet til denne artikkelen) kanskje kan vere på sin plass.

Unngå kompliserte beskrivelsesformater

Sidan eg har jobba litt opp mot NRKs publiseringssystemer, veit eg at XML-strukturen som Polopoly spytter ut er uhyre overflødig for John Johnsen som sit i kjelleren og utviklar ein OS X-applikasjon for nrknyheter.no. Responsen frå API-en burde vere godt strukturert og lett å jobbe opp mot. The Guardians dokumentasjon er eit godt eksempel på korleis det bør gjerast.
I tillegg til eit XML-grensesnitt bør også JSON vere eit tilgjengeleg databeskrivelsesformat, av fleire grunner:

  • – Det kan pluggast direkte inn i JavaScript
  • – Å beskrive ei ressurs via JSON tek mindre båndbredde og ressurser enn å gjere det via XML
  • JSON er mykje lettare å jobbe med enn XML i mange programmeringsspråk (blant anna Python).

API-tjenesta bør vere basert utelukkande på REST

Å tilby XML-RPC, SOAP og liknande arkitekturer er i det store og heile ikkje naudsynt. Fokusér på REST, og strukturer det skikkeleg.

Domenet http://api.nrk.no burde brukast som utgangspunkt til alle tenester (nettradio, kalenderdata, nyhende, osv…), men strukturerast etter tenestetype. Då ville f.eks. http://api.nrk.no/nyheter/ fungere som eit utgangspunkt for alle API-funksjoner relatert til nyhende.

Tillat god filtrering

La brukaren filtrere innholdet etter mange forskjellige vilkår, gjerne via enkle GET-parameter:

  • – Dato (før og etter)
  • – Kategori
  • – Saksunivers
  • – Tagger
  • – Skribent

Legg ved eksempel for utviklarane

The Guardian har gjort noko veldig lurt. I staden for å kun kaste dokumentasjonen ut til utviklarane, har dei lagt ved eksempel på implementasjon av API-en i Ruby, Python, Java og PHP. Dette gjer det veldig enkelt for oss som utviklarar å hoppe direkte inn og implementere API-en i vår applikasjon.

Nedanfor er eit kjapt eksempel på korleis ein kunne satt saman API-implementasjonen for Python:

Simon Willison, ein av hovudmennene bak The Guardian sin API, fortalde meg at dei har brukt i overkant av to og ein halv månad på å utvikle API-en, og eg kan ikkje gjere anna enn å gratulere dei med resultatet, samt kritisere tidsbruken til NRK. Eg vonar likevel at NRK klarer å utvikle eit produkt som er like gjennomført som dette.

I’m not bowled over much these days. But Guardian Open Platform is a chasmic leap into the future. It is a work of simplistic beauty that I’m sure will have a dramatic impact in the news market. The Guardian is already a market leader in the online space but Open Platform is revolutionary. It makes all of their major competitors look timid. – Tom Watson

Så kjem det obligatoriske spørsmålet: Korleis ønskjer du deg at API-en frå NRK skal fungere?

21 kommentarer

  1. Så lenge dere kjører på med REST så bør alle være fornøyde 🙂 Forhåpentligvis så kommer det Open Platform APIer for .NET også. Lykke til med satsingen og alt som åpnes opp for konsumering og miksing er positivt. Håper Finn.no gjør seg mer åpen i fremtiden.

    Svar på denne kommentaren

  2. Mats Taraldsvik

    Gleder meg til dette kommer på plass. Jeg laget et søkeprogram for å finne og vise nett-tv-videoer i python for en tid tilbake, men av en eller annen grunn var søkene litt upålitelige.

    God dokumentasjon er kanskje det aller viktigste. Det vel Mr. Willison skjønt fra før – Djangos dokumentasjon er jo veldig god.

    Eksempler i flere språk kommer jo også godt med. Min personlige favoritt er Python.

    Svar på denne kommentaren

  3. @SondreB: Det er sånn sett ingen problemer i å lage eit API-bibliotek for The Guardian sjølv – dei vedlagte eksempla er akkurat dét: eksempler.

    Det er jo for det meste Java og .NET internt i NRK, så det er ganske sjølvsagt at bibliotek for desse burde følgje ein eventuell API.

    @Mats Djangos dokumentasjon er vel blant dei bedre på nettet uansett tema, vil eg påstå. Men så er det ytterst få dokumentasjoner som er skrevet av faktiske journalister (Adrian Holovaty, Djangos co-founder er jo journalist) 🙂

    @Peter Korleis er XML bedre ved dataimport, egentlig?

    Svar på denne kommentaren

    • Spørs litt hvordan man definerer import, og jeg regnet egentlig med at det kunne bli tatt opp. (Skrev forrige innlegg fra mobilen, så var ikke så keen på å utbrodere. Treigt nok som det er å skrive)

      Med import mener jeg da typisk importrutiner, f.eks. som du finner i publiseringsverktøy. Disse forventer ofte en XML i et gitt format, og her kommer XML og XSLT inn. Man kan da ta inn omtrent hva som helst av XML, og bare legge på en XSLT og få XML i ønsket format.
      Noe sånt finnes såvidt jeg vet ikke for JSON.

      Annen fordel med XML er at man kan bruke tjenester som Yahoo pipes.
      Men forstå meg rett, jeg mener JSON stort sett er overleget, men XML har fortsatt noen få steder hvor det har sin plass. (Inntil videre ihvertfall)

    • Mats Taraldsvik (svar til Henrik Lied)

      Ah, Django ble vel utviklet for en lokalavis. Her i NRK har vi vel noen av disse ( jounalister med god, teknisk innsikt), så det er jo lov å krysse fingrene.

      Hvorfor trengs det api-nøkler, egentlig? Bruker man de i et program som publiseres (med kildekode), er det vel ikke lenger noen vits, eller? I hvert fall ikke hvis kontroll er hensikten. Dog, det kan jo være artig mtp. statistikk?

  4. Raymond Julin

    Definitivt JSON over XML (men tilby gjerne begge). Og definitivt REST. SOAP etc er totalt unødvendig og tungvindt. NRK burde faktisk vært lovfestet pliktig å tilby innholdet åpent ut siden vi alle er med og betaler kaka.
    Det er utrolig mange stedsforankrede sider på veven, og for disse er nyhetsfeeding fra NRK noe som bør være svært aktuelt, men da mange av disse sidene er drevet av lokale ildsjeler uten nødvendigvis stor greie burde NRK – når et API slippes – gjerne også lage en generator som lar deg enkelt generere javascript som henter ut det du har definert i generatoren. Da blir det svært enkelt for de uinvidde å sette opp noe fra NRK på sin side.

    Svar på denne kommentaren

  5. Hvilke tjenester er det som kan tilbys gjennom API-et? "Bare" nyheter, eller nett-tv-tjenester også? RSS-feed med videoene som går på "nyheter"-seksjonen på nett-tv? Hva med noe så kjedelig som tv-program for gitt dato/sendetider for gitt program?

    Svar på denne kommentaren

  6. Hyggelig å se at dere spør mulige klienter om tips før veivalgene tas. Det høres ut som dere har tenkt mye allerede:-) Men jeg kan prøve beskrive noen mer eller mindre personlige synspunkter og erfaringer – ikke minst fra arbeidet med FINNs REST API (ja, FINN har et REST API, men det er beklageligvis ikke åpent for alle).

    – Som du sier er REST eneste alternativ, perfekt til dette bruket
    – Greier dere å presentere XML og JSON er det bra, jeg ville også seriøst vurdert å følge Atom. Det skulle passe bra til NRKs innhold og gjør ting enklere for klientene (lag eget custom-format om nødvendig)
    – Bruk hypertext/linker hvis dere har noe i nærheten av en data-struktur. Eks.: <someXMLElement ref="http://api.nrk.no…" >… (bruk absolutte URLer). Klientene blir bedre dersom de kan navigere selv.

    – Uten å kjenne detaljene i The Guardian API'et høres det ut som mye kan lånes derfra. Dere har kanskje sjekket andre lignende tilbydere og vurdert eventuelle fellesnevnere eller "tendenser til standarder"? BBC, NBC etc.?
    – Tenk NOK over format, granularitet, parametere etc. før det er "for sent". Unngå endringer så langt det lar seg gjøre og drop tilbakekompatibilitet – informer heller klientene i god tid. Tilby evt. et testmiljø hvor klienter kan teste endringene hvis det mot formodning skulle være nødvendig.
    – Automatiserte tester som sjekker at tjenesten fungerer som den skal er nyttig. I FINN har vi utviklet et Ruby-basert rammeverk som sjekker at det ikke oppstår uautoriserte formatendringer, at HTTP-headere er riktig etc. Det gjør at man oppdager bugs før brukerne gjør det.
    – Lag et system for å få informasjon ut til klientene ved endringer etc. – en base med e-post adresser rekker et godt stykke. Hvis dere skal autentisere (hvilket jeg antar) er det vel ingen vei utenom.
    – Klienter bør kunne basere seg på å ikke cache på sin side, men spørre api.nrk.no "upon request". Derfor bør det være raskt (kanskje litt unødvendig å si, men igjen; brukeropplevelse). Siden disse dataene (artikler, audio, video?) kanskje ikke endrer seg etter at de først er publisert er det muligens en ypperlig anledning til å "Cache the hell out of it!"
    – Jeg vile beordret alle involverte i prosjektet til å lese "RESTful Web Services" av "Leonard Richardson" som hjemmelekse. REST-bibelen bør leses FØR man starter:-)
    – Dan Diephouse har en del konkrete råd, se evt. http://www4.java.no/javazone/2007/show.do%3Fpage=… Det også ligger en del nyttig på parleys.com.

    Det viktigste er vel kanskje at klientene skal opp og stå så raskt som mulig og generelt ha et uproblematisk liv. Derfor bør alt fungere så enkelt som mulig. Brukervennlighet er viktig rett og slett:
    – Enkel dokumentasjon i HTML, aller helst dynamisk (tilpasset hver enkelt klient hvis autentisering). Man bør slippe å leke frøken detektiv for å finne søkeparametere, lovlige verdier etc.
    – Eksempelkode i alle vanlige språk? JA! Eksempler er gjerne den beste dokumentasjon (ref. The Guardian).

    Venter spent på "fasiten" 😉

    Svar på denne kommentaren

  7. Jeg er fornøyd bare NRK klarer å få seg et API i det hele tatt, de tjenestene jeg ønsker jeg først er googlesøk, søk og utlistinger fra nett-tv, elektrinisk programguide og spillelisteinfo. På noen av disse finnes det api, men de er jo ikke eksponert utenfor NRK i noen større grad.

    Ellers er jeg stor fan av dokumentasjonen og formatene til audioscrobbler / last.fm. De har dog endret docuen til det verre, men den er fremdeles pent presentert, og nokså enkel å sette seg inn i http://www.last.fm/api

    Men en ting NRK burde gjøre var å også ta imot data. Det er fint å tilby data til folk, for verdien av innholdet stiger jo når folk blir "avhengige" av at det er der, men det er enda bedre om man klarer å få til data stores hvor folk kan legge inn og hente ut egen informasjon, a la youtube eller flickr. Et bra prosjekt i så måte kunne vært nrk.no/urort/, et bra api der kunne gjort at band kunne brukt urørt som storage for filer, og kunne ha oppdatert feks både egen side, urørt, facebook og myspace i en smell.

    Foto og videolagring burde jo også være innenfor NRKs "domene".

    m.

    Svar på denne kommentaren

  8. Dette ligner litt på det vi har gjort med SendRegning.no Web Services, dog ikke med REST og JSON. Vi har opprettet et repository hos Google Code der våre brukere kan laste ned klienter i sitt språk. Vi er helt i startfasen enda, men et sted må man jo begynne. Vi har også planer om å laste opp videoer som viser hvordan man kommer igang med de forskjellige klientene.

    http://code.google.com/p/sendregning-ws-clients/

    Vi vil nok stå for mesteparten av utviklingen av klientens selv, men vi håper jo virkelig på at folk bidrar med sine forbedringer ved å sende koden tilbake. Det skal bli spennende å følge med på.

    Svar på denne kommentaren

  9. Karsten skriver mye bra og riktig. Sats på åpne standarder; REST og JSON. Skal dere bruke XML, bruk Atom. Skal dere også i fremtiden støtte mottak (og ikke bare publisering) av data, bruk Atom Publishing Protocol.

    Husk å bruke REST på riktig måte. Hjelp til dette får dere i AtomPub, men skulle dere av en eller annen grunn velge en annen arkitektur (noe jeg vil fraråde), må dere i det minste huske at URI-ene skal designes som en hovedingrediens i API-et og at alle henvisninger til tilgjengelige ressurser i API-et skal bakes inn i andre ressurser (og ikke være forhåndsdefinert og hardkodet noe sted).

    Det skal f.eks. ikke være nødvendig å beskrive i API-dokumentasjonen hvilken URI man finner en artikkel-oversikt på, f.eks. API-et bør ha én inngangs-URI og ut fra denne bør resten være selvforklarende med bruk av URI-er inni alle ressurser som blir returnert. Ved å følge dette prinsippet får man et system som er veldig fleksibelt for endringer, da ingenting er hardkodet i klientene av API-et.

    Husk også å bruke GET, PUT, POST og DELETE til dét de er ment til. Ikke bruk POST til alt. Ikke bruk GET til å gjøre endringer. Ikke bruk PUT der POST er riktig, osv. AtomPub gir en veldig god innføring i hvordan disse metodene skal brukes for å få en riktig arkitektur og som til og med vil kunne glede en viss herr Fielding.

    Fordelene ved å følge disse prinsippene er mange. Fleksibilitet ifht endringer er nevnt; mulighet for caching er en annen. En tredje fordel som ligger i å bruke eksisterende formater og standarder er at det finnes en rekke klient-biblioteker tilgjengelig som utviklere kan basere seg på i kommunikasjon mot API-et. Ved å bruke AtomPub og Atom-formatet vil utviklere kunne benytte eksisterende biblioteker, nesten uansett hvilket programmeringsspråk de benytter seg av.

    Og sist men ikke minst; publiser tidlig og ofte, her på NRKBeta. På den måten vil jeg og andre som er interessert i slike ting kunne komme med tilbakemeldinger, samt å teste ut systemet, finne feil, o.l. før det produksjonssettes og gjøres tilgjengelig for almennheten. Til akkurat dette burde dere hatt et bug-rapporteringsverktøy. Har NRK noe slikt (Trac, FogBugz, Bugzilla, e.l.) offentlig tilgjengelig som kunne vært benyttet?

    Svar på denne kommentaren

Legg igjen en kommentar

Din e-postadresse vil ikke bli publisert. Obligatoriske felt er merket med *. Les vår personvernserklæring for informasjon om hvilke data vi lagrer om deg som kommenterer.