Share
Flickr, de grootste website voor het beheren en delen van foto's ter wereld, heeft een indrukwekkende API om ontwikkelaars toegang te geven tot bijna alle gegevens en deze te manipuleren. Laten we eens kijken hoe we met de API kunnen werken: op het laagst mogelijke niveau.
In dit Web 2.0-tijdperk hebben webtoepassingen met een eenvoudig te gebruiken, intuïtieve API een duidelijk voordeel omdat ontwikkelaars het platform kunnen gebruiken en bouwen en zo meer gebruikers kunnen vastleggen. Naarmate we dichter bij het sociale web en mashups komen, is een goede API geen leuke toevoeging meer: het is ronduit noodzakelijk. En onthoud dat te veel abstractie nooit een goede zaak is. Hoewel er een aantal API-kits beschikbaar zijn om het werken met de API in kwestie te vereenvoudigen, zou het niet cool zijn om te weten wat er feitelijk gaande is onder de motorkap? Zou het niet spannend zijn om de werkelijke voodoo die zich tussen de kit en de API afspeelt te deconstrueren? Ja dat dacht ik al! In deze nieuwe serie zullen we de API's van enkele van de populairste services die er zijn bekijken. Vandaag bekijken we de Flickr API.
De tango tussen de ontwikkelaar en API begint en culmineert in een reeks goed gedefinieerde stappen. Ik zal elke stap uitleggen als we gaan.
Allereerst moeten we beslissen welk type applicatie we gaan bouwen. Desktop-applicaties hebben om het bureaubladmodel te gebruiken terwijl een webtoepassing een van de modellen kan gebruiken. Het mobiele model valt buiten het bestek van dit artikel.
Voor dit artikel heb ik gekozen voor het desktopmodel, omdat het webmodel vereist dat alle tests worden uitgevoerd op het domein waarop de app moet worden geïmplementeerd. Dit is misschien niet per se voor veel mensen haalbaar. We kiezen het desktopmodel omdat het deze beperking niet heeft.
De volgende stap is het verkrijgen van een applicatiesleutel. Flickr gebruikt deze app-sleutel om ons gebruik en andere statistieken bij te houden. Ga hierheen en solliciteer voor uw eigen API-sleutel.
Omdat ons gebruik van deze specifieke API-sleutel puur educatief is, kiezen we ervoor om een niet-commerciële sleutel te verkrijgen.
Vul alle details in die het formulier nodig heeft, met speciale aandacht voor de beschrijving van het project. De ontwikkelaars van Flickr lezen deze beschrijving als je app zich op de een of andere manier misdraagt om er zeker van te zijn dat het legitiem is. Dus besteed die extra minuut aan je beschrijving van je meesterwerk.
Een succesvolle registratie levert u deze pagina op. Noteer de api-sleutel en het gedeelde geheim voor later gebruik.
De Flickr API biedt een aantal methoden die al dan niet verificatie vereisen. Elke methode heeft een aantal argumenten nodig die het gedrag en de nuttige lading wijzigen. Reacties kunnen worden ontvangen in een aantal indelingen, waaronder JSON, XML, SOAP en REST. Al deze verzoeken kunnen worden gedaan aan eindpunten die overeenkomen met het formaat dat u hebt gekozen om het verzoek in te dienen. We zullen bijvoorbeeld REST gebruiken voor de rest van dit artikel en daarom zou ons URL-eindpunt zijn: http: // api .flickr.com / diensten / rust /.
Er zijn een aantal methoden die openbare gegevens ophalen en dus geen enkele verificatie vereisen. We hebben alleen de api-sleutel nodig die we eerder hadden verkregen, samen met de vereiste argumenten van de methode in kwestie. Laten we een kijkje nemen naar een voorbeeld.
De methode getPublicGroups is een voorbeeld van een methode waarvoor geen verificatie vereist is en die openbare gegevens ophaalt. We geven het gebruikers-ID van de gebruiker en onze api-sleutel door en de API reageert in de door u gevraagde indeling met een lijst met groepen waarvan de gebruiker deel uitmaakt.
We sturen een verzoek naar deze URL.
http://api.flickr.com/services/rest/?method=flickr.people.getPublicPhotos&api_key=your_api_key&user_id=user_id_x
Vervangen your_api_key met de sleutel die we eerder hebben verkregen en user_id_x met een geldige NSID. Omdat ik vind dat mijn antwoorden in JSON zitten, kan ik een andere parameter toevoegen waarin de API wordt gevraagd om te reageren met een JSON-payload.
http://api.flickr.com/services/rest/?method=flickr.people.getPublicPhotos&api_key=your_api_key&user_id=user_id_x&format=json
De API stuurt een antwoord als volgt:
Accentsconagua
jsonFlickrApi ("photos": "page": 1, "pages": 1, "perpage": 100, "total": "2", "photo": ["id": "3728895285", "eigenaar ":" 40318902 @ N02 "," secret ":" df6dfee053 "," server ":" 3466 "," farm ": 4," title ":" opac "," ispublic ": 1," isfriend ": 0, "isfamily": 0, "id": "3729689790", "owner": "40318902 @ N02", "secret": "ea9c38a675", "server": "2531", "farm": 3, "title ":" scale "," ispublic ": 1," isfriend ": 0," isfamily ": 0,]," stat ":" ok ") Goed geformatteerd, het zal er zo uitzien.
jsonFlickrApi ("photos": "page": 1, "pages": 1, "perpage": 100, "total": "2", "photo": ["id": "3729689790", "eigenaar ":" 40318902 @ N02 "," secret ":" ea9c38a675 "," server ":" 3466 "," farm ": 4," title ":" opac "," ispublic ": 1," isfriend ": 0, "isfamily": 0, "id": "3729689845", "owner": "40318902 @ N02", "secret": "df6dfee053", "server": "2531", "farm": 3, "title ":" scale "," ispublic ": 1," isfriend ": 0," isfamily ": 0]," stat ":" ok ") Dit is waarschijnlijk de reden dat je wilt leren werken met de Flickr API en daarom zullen we elke stap langzaam doen, omdat dit deel de neiging heeft om mensen te verwarren.
Voor het verkrijgen van privégegevens heeft elke methode verificatie nodig en voor verificatie moet elk van onze oproepen worden ondertekend. Ondertekenen werkt als volgt:
Maak een alfabetisch gesorteerde lijst van de argumenten
In het vorige voorbeeld zou onze lijst er bijvoorbeeld zo uitzien:
Maak de handtekeningstring
De handtekeningstring wordt gemaakt door de API geheim we hebben eerder verkregen en vervolgens de lijst met argumenten eraan toegevoegd. Onze handtekeningreeks ziet er bijvoorbeeld zo uit:
0123456789api_keyxxxformatjsonuseridyyy
Onze oproep ondertekenen
De laatste stap is de daadwerkelijke ondertekening. Flickr verwacht dat we de MD5-hash van onze handtekeningreeks nemen en deze aan onze oorspronkelijke methodeaanroep toevoegen als een parameter met de naam.
Dus elke geverifieerde oproep heeft dit algemene formaat
http://api.flickr.com/services/rest/?method=ourmethod&api_key=apikey&api_sig=hashedvalue
Nu met het uitloggen, kunnen we nu doorgaan naar de daadwerkelijke authenticatie. Flickr gebruikt een systeem vergelijkbaar met OAuth voor autorisatie, wat betekent dat een gebruiker die onze app wil gebruiken, zijn / haar gebruikersreferenties niet hoeft te onthullen. Gebruikers worden naar de Flickr-website gebracht waar de gebruiker wordt gevraagd of hij / zij onze app toegang tot de gegevens van de gebruiker wil geven.
Dit is waar a frob komt binnen. Om de inlogkoppeling te maken die de gebruiker naar een autorisatiepagina op Flickr brengt, hebben we een manier nodig om een specifieke login-sessie te identificeren.
Om een frob te verkrijgen om de sessie te identificeren, moeten we de flickr.auth.getFrob het doorgeven van onze api-sleutel als een benoemd argument. Onze URL zou er zo uit zien:
http://api.flickr.com/services/rest/?method=flickr.auth.getFrob&api_key=apikey&api_sig=hashedvalue
Een JSON-reactie ziet er als volgt uit:
frobcallback ("frob": "_content": "xxx", "stat": "ok") Nadat we met succes een frob hebben verkregen, kunnen we nu werken aan het bouwen van de URL waarmee de gebruiker onze applicatie kan autoriseren. De inlog-URL heeft dit algemene formaat:
http://flickr.com/services/auth/?api_key=apikey&api_sig=apisig&perms=perms&frob=frob
Vervang de waarde van api_key door de waarde die we eerder hadden verkregen, de waarde van api_sig met een MD5-hash van onze tekenreeks en frob-waarde met de frob-waarde die door de API wordt geretourneerd. De permanenten parameter definieert het gewenste niveau van accounttoegang en heeft geldige waarden van lezen, schrijven en verwijderen. Elke toegang omvat de rechten van al zijn voorgangers.
Een geldige inlog-URL heeft dit formulier:
http://flickr.com/services/auth/?api_key=63b08e2efcc22de9900163f4d761fdbc&api_sig=663369798c695dbe2fd7e2af7576dd2b&perms=delete&frob=72157621742082858-8e995a1104e28114-870912
De autorisatiepagina's zien er zo uit:
Nadat de gebruiker toestemming heeft gegeven voor onze aanvraag, kunnen we doorgaan. De laatste stap in dit proces is het verkrijgen van een auth_token. Een auth-token verbindt een specifieke API-sleutel aan een specifieke gebruikers-ID, d.w.z. een auth-token kan worden gebruikt om alleen de gegevens van een specifieke gebruiker te manipuleren terwijl een specifieke API-sleutel wordt gebruikt. Een auth-token is nodig voor elke API-methode aanroep waarvoor verificatie is vereist.
Het verkrijgen van een auth token is zo simpel als het aanroepen van de flickr.auth.getToken methode die de api key, frob en api-signatuur doorgeeft als benoemde parameters. De URL zou er zo uit zien:
http://flickr.com/services/auth/?api_key=apikey&api_sig=apisig&frob=frob
Een succesvol verzoek plaatst ons een auth-token dat onbeperkt kan worden gebruikt om toegang te krijgen tot de gegevens van een specifieke gebruiker met behulp van een specifieke api-sleutel.
Nu aan alle voorwaarden is voldaan, kunnen we gegevens ophalen als dat nodig is. Vergeet niet dat elk van uw geverifieerde oproepen moet worden ondertekend en daarom moet elke oproep de api_key, auth_token en api_sig voor de methodeoproep naar het werk verzenden.
Op basis van het minimum moet de URL voor uw REST-aanvraag er zo uitzien. Andere methodespecifieke parameters of parameters die de payload wijzigen, kunnen indien nodig worden toegevoegd.
http://flickr.com/services/auth/?api_key=xxx&api_sig=yyy&auth_token=zzz&method=method_name
Zorg er tijdens het ondertekenen voor dat u ook de andere argumenten en hun waarden opneemt. Dit is een veel voorkomende oorzaak van fouten en hoofdpijn en kan gemakkelijk worden verholpen. Neemt u de callback-parameters op in de URL om de cross-domeinbeperking in browsers te voorkomen tijdens het gebruik van AJAX? Die moeten ook in de handtekeningstring gaan!
Laten we een voorbeeld van een reactie bekijken op een methode die openbare foto's retourneert.
jsonFlickrApi ("photos": "page": 1, "pages": 1, "perpage": 100, "total": "2", "photo": ["id": "3729689790", "eigenaar ":" 40318902 @ N02 "," secret ":" ea9c38a675 "," server ":" 3466 "," farm ": 4," title ":" opac "," ispublic ": 1," isfriend ": 0, "isfamily": 0, "id": "3729689845", "owner": "40318902 @ N02", "secret": "df6dfee053", "server": "2531", "farm": 3, "title ":" scale "," ispublic ": 1," isfriend ": 0," isfamily ": 0]," stat ":" ok ") Het is allemaal prima en dandy, maar de reactie bevat geen URL waarnaar we een koppeling kunnen maken. In plaats daarvan moeten we een URL voor de betreffende afbeelding maken op basis van de gegevens die van de server zijn verzonden. Hier is hoe:
De URL van elke afbeelding op Flickr volgt een duidelijk gedefinieerd patroon. Ontgrendel dit en het antwoord begint veel logischer te worden. Hier is de URL van een afbeelding in mijn account.
http://farm3.static.flickr.com/2531/3729689790_ea9c38a675_b.jpg
De URL bestaat uit een aantal delen:
Kortom, om de bron van de afbeelding te construeren, zou de link er uitzien zoals de hieronder getoonde als we gemaakt waren om de JSON-respons te ontleden waarbij gegevens de variabele is die het antwoord bevat:
"http: // farm" + data.photos.photo [i] .farm + ".static.flickr.com /" + data.photos.photo [i] .server + "/" + data.photos.photo [ i] .id + "_" + data.photos.photo [i] .secret + ".jpg
Nu we hebben bekeken hoe we gegevens van Flickr kunnen ophalen met behulp van de API, is het tijd om te kijken hoe we gegevens terug kunnen sturen.
De upload-API van Flickr is anders dan zijn REST- of SOAP-gebaseerde API's omdat er geen URL-eindpunten zijn die u gewoon kunt openen en ophalen. In plaats daarvan moeten gegevens worden verzonden via een POST-aanvraag naar
http://api.flickr.com/services/upload/
Aangezien het buiten het bestek van dit artikel valt om u te laten zien hoe u een POST-query helemaal opnieuw kunt construeren, gebruiken we een formulierelement met een enctype-waarde van multipart / form-data om alle code voor ons te genereren. Met behulp van dit bepaalde kenmerk kunnen we stellen dat het formulier binaire gegevens bevat en als zodanig moet worden verwerkt. Een voorbeeldformulier ziet er als volgt uit.
Maar vergeet niet dat we nog steeds een aantal parameters naar de service moeten sturen, inclusief de api-sleutel, auth-token en de methodesignatuur. Hoe doen we dat? Het is gewoon een kwestie van een verborgen tekstveld maken en hun waarde aanpassen om de juiste waarden weer te geven. Zoals zo:
Onthoud dat tijdens het genereren van de MD5-hash van de handtekeningstring die u moet uploaden elk element van het formulier met uitzondering van het fotoveld. Dit omvat de waarde van de submit-knop, omdat de inhoud van het volledige formulier naar de URL wordt gepost. Voor het bovenstaande voorbeeld zou de hash als volgt moeten worden berekend:
var hash = MD5 (geheim + "api_key" + apikey + "auth_token" + token + "submitUpload");
Je bent niet helemaal beperkt tot die argumenten. De upload-API gebruikt een aantal argumenten, waaronder de titel van de foto, de titel en beschrijving. Als je dat wilde, kon je net zo gemakkelijk de gebruiker al die gegevens laten invoeren, samen met privacy-instellingen zoals:
Een artikel over het werken met de API van een service zou duidelijk onvolledig zijn zonder een blik te werpen op enkele van de meest gebruikte API-methoden. Met dat in gedachten, hier zijn een paar API-methoden die zeer nuttig zouden moeten zijn, ongeacht of je een mashup aan het maken bent of gewoon op zoek bent om je eigen data op te halen.
Vergeet niet dat voor geverifieerde oproepen geldige waarden nodig zijn om de parameters api_key, api_sig en auth_token te laten werken terwijl normale oproepen wel of niet specifieke parameters voor de methode vereisen. Allemaal oproepen vereisen dat de parameter api_key wordt verzonden. Dus als ik vermeld dat de oproep authenticatie vereist, impliceert het feit dat de oproep de andere argumenten vereist impliciet. De hieronder vermelde argumenten zijn optioneel tenzij anders vermeld. Methoden die een lijst met gegevens retourneren, nemen ook een argument op een pagina en per_page om hun naamgenoten te definiëren.
Ik heb reacties van elke methode opgenomen om u een idee te geven van de gegevens die aan ons zijn geleverd. Ik ben met JSON meegegaan als antwoordformat sinds de meeste ontwikkelaars waarmee ik werk, zoals JSON, beter dan XML.
flickr.activity.userPhotos
Retourneert een lijst met recente activiteit op foto's van de bellende gebruiker.
argumenten: tijdframe - bepaalt het tijdsbestek waarin moet worden gezocht naar updates.
authenticatie: Ja
antwoord
"items": "item": ["type": "photo", "id": "3728895285", "owner": "40318902 @ N02", "ownername": "lordtottuu", "secret": "df6dfee053", "server": "3466", "farm": 4, "title": "_content": "opac", "commentold": 1, "commentsnew": 0, "notesold": 0, "notesnew": 0, "views": 0, "faves": 0, "more": 0, "activity": "event": ["type": "comment", "commentid": "40298554- 3728895285-72157621628251433 "," gebruiker ":" 40318902 @ N02 "," gebruikersnaam ":" lordtottuu "," dateadded ":" 1248131143 "," _content ":" Demo-afbeelding voor mijn aanstaande artikel over Net Tuts "] ], "pagina": 1, "pagina's": 1, "perpagina": 10, "totaal": 1, "stat": "ok"
flickr.contacts.getList
Retourneert een lijst met contactpersonen voor de bellende gebruiker.
argumenten: filter - Argument om de lijst te filteren. Geldige waarden zijn vrienden, familie, beide en geen van beide.
authenticatie: Ja
antwoord
"contacts": "page": 1, "pages": 1, "per_page": 1000, "perpage": 1000, "total": 2, "contact": ["nsid": "7488445 @ N05 "," gebruikersnaam ":" thegleek "," pictogrammen server ":" 179 "," iconfarm ": 1," ignored ": 0," realname ":" Mike Poleski "," friend ":" 1 "," family " : "0", "path_alias": null, "location": ""] // Rest van de contacten, "stat": "ok"
flickr.favorites.getList
Retourneert een lijst met foto's die door een specifieke gebruiker als favoriet zijn gemarkeerd.
argumenten: min_fave_date, max_fav_date - Spreekt voor zich.
authenticatie: Ja
antwoord
"photos": "page": 1, "pages": 1, "perpage": 100, "total": "3", "photo": ["id": "2332823355", "owner": "53555705 @ N00", "secret": "e603be40a2", "server": "2333", "farm": 3, "title": "Xbox 360 stilleven", "ispublic": 1, "isfriend": 0 , "isfamily": 0, "date_faved": "1248134938"] // Rest van de foto's, "stat": "ok"
flickr.people.getPublicPhotos
Krijg een lijst met openbare foto's voor de gegeven gebruiker.
argumenten: nsid [verplicht] - ID van de bellende gebruiker, safe_search - Om NSFW-inhoud te blokkeren.
authenticatie: Nee
antwoord
"photos": "page": 1, "pages": 1, "perpage": 100, "total": "15", "photo": ["id": "3728895285", "owner": "40318902 @ N02", "secret": "df6dfee053", "server": "3466", "farm": 4, "title": "opac", "ispublic": 1, "isfriend": 0, "isfamily ": 0] // Rest van de foto's," stat ":" ok "
flickr.groups.getInfo
Informatie verkrijgen over een bepaalde groep.
argumenten: group_id [verplicht] - De ID van de groep waarover u informatie zoekt.
authenticatie: Nee
antwoord
"group": "id": "51035612836 @ N01", "iconserver": "1", "iconfarm": 1, "name": "_content": "Flickr API", "description": "_content": string "Een Flickr-groep voor Flickr API-projecten." Bewustwording van de Flickr API, projecten die het gebruiken en die ongelooflijke ideeën die programmatisch blootgestelde systemen produceren. "Denk aan Google API + Amazon API + Flickr API met een beetje GMail gegooid De ontwikkelaars van Flickr hebben er terecht op gewezen dat ze technische besprekingen willen houden die direct verband houden met de API op de mailinglijst. " , "members": "_content": "7775", "privacy": object "_content": "3", "lang": null, "ispoolmoderated": 1, "throttle": object " count ":" 3 "," mode ":" day "," restrictions ": object " photos_ok ": 1," videos_ok ": 1," images_ok ": 1," screens_ok ": 1," art_ok ": 1, "safe_ok": 1, "moderate_ok": 0, "restricted_ok": 0, "has_geo": 0, "stat": "ok"
flickr.photos.getExif
Expenseert EXIF-gegevens van een bestaande foto .
argumenten: photo_id [vereist] - ID van de foto waarvan de EXIF-gegevens moeten worden geëxtraheerd.
authenticatie: Nee
antwoord
"photo": "id": "2332823355", "secret": "e603be40a2", "server": "2333", "farm": 3, "exif": ["tagspace": "TIFF", "tagspaceid": 1, "tag": 271, "label": "Make", "raw": "_content": "Canon", "tagspace": "TIFF", "tagspaceid": 1, "tag": 272, "label": "Model", "onbewerkt": "_content": "Canon EOS 350D DIGITAL", // Rest van de exif-gegevens], "stat": "ok"
flickr.photos.geo.getLocation
Retourneert de breedte- en lengtegraad van de plaats waar een specifieke foto is gemaakt.
argumenten: photo_d [vereist] - ID van de foto waarvan de locatie bekend moet zijn.
authenticatie: Nee
antwoord
"photo": object "id": string "229097925", "location": object "latitude": -33.856874, "longitude": 151.214672, "accuracy": "16", "context": "0" , "lokaliteit": "_content": "Sydney", "place_id": "p50kaZyYAJx9BZHQ", "woeid": "1105779", "region": object "_content": "New South Wales", "place_id" : "puGzSeubAphuNnF2", "woeid": "2344700", "country": object "_content": "Australia", "place_id": "om3Zr2abAphqrm3jdA", "woeid": "23424748", "place_id": string "p50kaZyYAJx9BZHQ", "woeid": string "1105779", "stat": string "ok"
flickr.photos.getFavorites
Retourneert een lijst met mensen die de gepleegde foto als favoriet hebben gemarkeerd.
argumenten: photo_id [verplicht] - ID van de betreffende foto.
authenticatie: Nee
antwoord
"foto": "persoon": ["nsid": "39011391 @ N06", "gebruikersnaam": "derek1960", "favedate": "1243834286", // Rest van de foto's], "id" : "229097925", "secret": "13a21546fb", "server": "61", "farm": 1, "pagina": 1, "pagina's": 2, "perpagina": 10, "totaal": " 18 "...," stat ":" ok "
flickr.places.getTopPlacesList
Retourneert een lijst met de 100 meest getagde plaatsen voor een dag.
argumenten: place_type_id [verplicht] - Numeriek ID van een plaats om te definiëren hoe foto's worden geclusterd.
authenticatie: Nee
antwoord
"places": object "total": number100, "place": ["place_id": "4KO02SibApitvSBieQ", "woeid": "23424977", "latitude": "48.890", "longitude": "-116.982 "," place_url ":" / United + States "," place_type ":" country "," place_type_id ":" 12 "," _content ":" United States "," photo_count ":" 23654 ", // Rest van de 99 landen], "date_start": 1248048000, "date_stop": 1248134399, "stat": "ok"
flickr.tags.getHotList
Retourneert een lijst met meest gebruikte tags voor een bepaalde periode.
argumenten: period - Specificeert de periode waarvoor de tags worden verkregen. count - Specificeert het aantal te retourneren tags in het antwoord.
authenticatie: Nee
antwoord
"hottags": "period": "day", "count": 20, "tag": ["score": "100", "_content": "sundaystreets", "score": "100 "," _content ":" happymondayblues ", " score ":" 100 "," _content ":" melbourneopenhouse2009 "]," stat ": string" ok "
In dit openingsgedeelte van de serie hebben we gekeken hoe we met de Flickr API kunnen werken, inclusief hoe we openbare en privégegevens kunnen ophalen, authenticeren met de API en hoe we gegevens naar de service kunnen uploaden. We hebben ook een aantal van de meest gebruikte API-methoden samen met hun JSON-reacties bekeken om een beter inzicht te krijgen in de structuur van de gegevens die de API terugstuurt.
Welke API hierna wordt behandeld, is geheel aan jou. Hier, bij Net Tuts, spelen we in op de populaire vraag en daarom laten we jou, de lezers, beslissen welke API van de service over de volgende zal worden geschreven. Laat in je reactie hieronder, indien nodig, de naam van de service en de API-interface achter. We hebben REST behandeld in dit artikel, maar we willen graag SOAP-gebaseerde of op XML-RPC gebaseerde API's behandelen als voldoende mensen dit willen.
Vragen? Leuke dingen om te zeggen? Kritiek? Klik op het gedeelte Opmerkingen en laat een opmerking achter. Happy codering!
