Share
Flickr, som är den största bildhanterings- och delningsplatsen i världen, har ett imponerande API för att låta utvecklare komma åt och manipulera nästan alla sina data. Låt oss se hur vi arbetar med API: på lägsta möjliga nivå.
I den här Web 2.0-tiden har webbprogram som har ett lättanvänt, intuitivt API en tydlig fördel eftersom det låter utvecklare utnyttja och bygga för plattformen och därmed fånga fler användare. När vi flyttar mot socialwebben och mashups är ett bra API inte ett bra tillägg längre: det är absolut nödvändigt. Och kom ihåg att mycket abstraktion är aldrig en bra sak. Även om det finns ett antal API-paket där ute för att förenkla arbetet med det aktuella API-en, skulle det inte vara coolt att veta vad som verkligen händer under huven? Skulle det inte vara spännande att dekonstruera den faktiska voodoo som händer mellan satsen och API: n? Ja, jag trodde det! I den här nya serien tar vi en titt på API: erna för några av de mest populära tjänsterna där ute. Idag tar vi en titt på Flickr API.
Tangansen mellan utvecklaren och API börjar och kulminerar i en rad väldefinierade steg. Jag förklarar varje steg när vi går.
Först av allt måste vi bestämma vilken typ av ansökan vi ska bygga. Skrivbordsprogram ha att använda skrivbordsmodellen medan en webbapplikation kan använda någon av modellerna. Mobilmodellen ligger utanför ramen för denna artikel.
För denna artikel har jag valt att gå med skrivbordsmodellen eftersom webbmodellen kräver att alla testning görs på domänen där appen ska distribueras. Det kanske inte nödvändigtvis är möjligt för många människor. Vi väljer skrivbordsmodellen eftersom den saknar denna begränsning.
Nästa steg är att få en applikationsnyckel. Flickr använder den här appnyckeln för att hålla flikar över vår användning och annan statistik. Håll dig här och ansöka om din egen API-nyckel.
Eftersom vår användning av denna speciella API-nyckel är rent utbildad väljer vi att erhålla en icke-kommersiell nyckel.
Fyll i alla detaljer som formuläret kräver med särskild hänsyn till beskrivningen av projektet. Dev devs på flickr läste faktiskt denna beskrivning om din app misbehaves på något sätt för att se till att det är legit. Så spendera den extra minuten som beskriver ditt mästerverk.
En framgångsrik registrering ger dig den här sidan. Notera ner api-tangenten och den delade hemligheten för senare användning.
Flickr API tillhandahåller ett antal metoder som kanske eller inte kräver autentisering. Varje metod tar ett antal argument som modifierar sitt beteende och nyttolast. Svar kan tas emot i ett antal format, inklusive JSON, XML, SOAP och REST. Alla dessa önskemål kan göras till slutpunkter som motsvarar det format du har valt för att göra förfrågan. Till exempel använder vi REST för resten av den här artikeln och så är vår slutadress för webbadressen http: // api .flickr.com / tjänster / vila /.
Det finns ett antal metoder som drar in offentliga data och kräver sålunda ingen autentisering av något slag. Vi behöver bara den api nyckeln vi hade erhållit tidigare tillsammans med eventuella argument av den aktuella metoden. Låt oss titta på ett exempel.
Metoden getPublicGroups är ett exempel på en metod som inte kräver autentisering och som drar in offentliga data. Vi skickar in användarens användarnamn och vår api-nyckel och API svarar i det format du begärde med en lista över grupper användaren är en del av.
Vi skickade en förfrågan till den här webbadressen.
http://api.flickr.com/services/rest/?method=flickr.people.getPublicPhotos&api_key=your_api_key&user_id=user_id_x
Byta ut your_api_key med nyckeln vi erhållit tidigare och user_id_x med en giltig NSID. Eftersom jag gillar att jag svarar på att vara i JSON kan jag lägga till en annan parameter som ber API: n att svara med en JSON nyttolast.
http://api.flickr.com/services/rest/?method=flickr.people.getPublicPhotos&api_key=your_api_key&user_id=user_id_x&format=json
API: n skickar ett svar som så:
Accentsconagua
jsonFlickrApi ("foton": "sida": 1, "sidor": 1, "perpage": 100, "totalt": "2", "foto": ["id": "3728895285" ":" 40318902 @ N02 "," hemlig ":" df6dfee053 "," server ":" 3466 "," gård ": 4," titel ":" opac "," ispublic ": 1," isfriend " "isfamily": 0, "id": "3729689790", "ägare": "40318902 @ N02", "hemligt": "ea9c38a675", "server": "2531", "gård" ":" skala "," ispublic ": 1," isfriend ": 0," isfamily ": 0,]," stat ":" ok ") Korrekt formaterad, det kommer att se ut så här.
jsonFlickrApi ("foton": "sida": 1, "sidor": 1, "perpage": 100, "totalt": "2", "foto": ["id": "3729689790" ":" 40318902 @ N02 "," hemlighet ":" ea9c38a675 "," server ":" 3466 "," gård ": 4," titel ":" opac "," ispublic ": 1," isfriend " "isfamily": 0, "id": "3729689845", "ägare": "40318902 @ N02", "hemligt": "df6dfee053", "server": "2531", "gård" ":" skala "," ispublic ": 1," isfriend ": 0," isfamily ": 0]," stat ":" ok ") Det här är förmodligen anledningen till att du vill lära dig hur du arbetar med Flickr API och så går vi långsamt över varje steg, eftersom den här delen har en tendens att förvirra människor.
För att erhålla privat data behöver varje metod autentisering och för autentisering för att fungera måste alla samtal signeras. Signering fungerar som så:
Gör en alfabetiskt sorterad lista över argumenten
Till exempel, i föregående exempel skulle vår lista se ut så här:
Skapa signatursträngen
Signatursträngen skapas genom att ta API-hemlighet vi har erhållit tidigare och sedan bifogar listan över argument till den. Till exempel ser vår signatursträng ut så här:
0123456789api_keyxxxformatjsonuseridyyy
Signera vårt samtal
Det sista steget är den faktiska signeringen. Flickr förväntar oss att vi tar MD5-hash av vår signatursträng och lägger den till vårt ursprungliga metodsamtal som en namngiven parameter.
Så vilket autentiserat samtal har detta generella format
http://api.flickr.com/services/rest/?method=ourmethod&api_key=apikey&api_sig=hashedvalue
Nu med signeringen ur vägen kan vi nu gå vidare till den faktiska autentiseringen. Flickr använder ett system som liknar OAuth för behörighet vilket innebär att en användare som vill använda vår app inte behöver avslöja sina användaruppgifter. Användare transporteras till Flickrs webbplats där användaren frågas om han / hon vill tillåta att vår app får åtkomst till användarens data.
Det är här a FROB kommer in. För att skapa inloggningslänken som tar användaren till en behörighetssida på Flickr behöver vi ett sätt att identifiera en specifik inloggningssession.
För att få en frob för att identifiera sessionen måste vi ringa flickr.auth.getFrob passerar vår api nyckel som namnet argument. Vår URL skulle se ut så här:
http://api.flickr.com/services/rest/?method=flickr.auth.getFrob&api_key=apikey&api_sig=hashedvalue
Ett JSON-svar ser ut så här:
frobcallback ("frob": "_content": "xxx", "stat": "ok") Med framgång har vi fått en frob, vi kan nu arbeta för att bygga upp webbadressen som låter användaren godkänna vår ansökan. Inloggningsadressen har det här generella formatet:
http://flickr.com/services/auth/?api_key=apikey&api_sig=apisig&perms=perms&frob=frob
Ersätt api_keys värde med det vi hittat tidigare, api_sigs värde med en MD5-hash av vår signatursträng och frossens värde med det frövärde som returneras av API: n. De permanenter parameter definierar önskad nivå av kontoåtkomst och har giltiga värden för läs, skriv och ta bort. Varje åtkomst omfattar alla sina föregångares rättigheter.
En giltig inloggningsadress tar detta formulär:
http://flickr.com/services/auth/?api_key=63b08e2efcc22de9900163f4d761fdbc&api_sig=663369798c695dbe2fd7e2af7576dd2b&perms=delete&frob=72157621742082858-8e995a1104e28114-870912
Godkännandet sidor ser ut så här:
När användaren har gett tillstånd för vår ansökan kan vi fortsätta framåt. Det sista steget i denna process är att erhålla en auth_token. En auth token knyter en specifik API-nyckel till ett specifikt användar-ID, dvs en auth token kan användas för att manipulera endast en specifik användares data medan en specifik API-nyckel används. En autentoken är nödvändig för varje API-metallsamtal som kräver autentisering.
Att få ett autentoken är lika enkelt som att ringa flickr.auth.getToken metod som passerar i api-tangenten, frob- och api-signaturen som namngivna parametrar. URL: n skulle se ut så här:
http://flickr.com/services/auth/?api_key=apikey&api_sig=apisig&frob=frob
En framgångsrik förfrågan ger oss en auth token som kan användas obestämt för att få tillgång till en specifik användares data med en viss api-nyckel.
Nu, att alla förutsättningar har uppfyllts, kan vi gå om att hämta data efter behov. Kom ihåg att var och en av dina autentiserade samtal måste signeras och så varje samtal måste skicka in api_key, auth_token och api_sig för att metoden samtalar till jobbet.
Vid basminimum måste webbadressen för din REST-förfrågan se ut så här. Andra metodspecifika parametrar eller parametrar som ändrar nyttolast kan bifogas vid behov.
http://flickr.com/services/auth/?api_key=xxx&api_sig=yyy&auth_token=zzz&method=method_name
Undertecknandet, se till att även inkludera de andra argumenten och deras värden. Detta är en vanlig orsak till fel och huvudvärk och kan lätt åtgärdas. Inkluderar du återuppringningsparametrar i webbadressen för att undvika gränsöverskridande domänbegränsning i webbläsare medan du använder AJAX? De måste också gå in i signatursträngen!
Låt oss ta en titt på ett exempel svar för en metod som returnerar offentliga foton.
jsonFlickrApi ("foton": "sida": 1, "sidor": 1, "perpage": 100, "totalt": "2", "foto": ["id": "3729689790" ":" 40318902 @ N02 "," hemlighet ":" ea9c38a675 "," server ":" 3466 "," gård ": 4," titel ":" opac "," ispublic ": 1," isfriend " "isfamily": 0, "id": "3729689845", "ägare": "40318902 @ N02", "hemligt": "df6dfee053", "server": "2531", "gård" ":" skala "," ispublic ": 1," isfriend ": 0," isfamily ": 0]," stat ":" ok ") Det är allt bra och dandigt men svaret innehåller inte en URL som vi bara kunde länka till. I stället måste vi konstruera en URL för den aktuella bilden baserat på data som skickas tillbaka från servern. Så här är det:
Egens bildadress på Flickr följer ett väldefinierat mönster. Lås upp det här och svaret börjar göra mycket mer meningsfullt. Här är webbadressen till en bild i mitt konto.
http://farm3.static.flickr.com/2531/3729689790_ea9c38a675_b.jpg
Webbadressen är gjord av ett antal delar:
Kort sagt, för att bygga bildkällan, skulle länken se ut som den som visas nedan om vi gjordes för att analysera JSON-svaret där data är variabeln som rymmer svaret:
"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 när vi har tittat på hur man hämtar data från Flickr med hjälp av dess API, är det dags att titta på hur man skickar data tillbaka.
Flickrs uppladdnings API skiljer sig från dess REST- eller SOAP-baserade API: er eftersom det inte finns några URL-ändpunkter som du bara kunde få tillgång till och hämta data. I stället måste data skickas via en POST-förfrågan till
http://api.flickr.com/services/upload/
Eftersom det ligger utanför ramen för denna artikel för att visa dig hur du konstruerar en POST-fråga från början, använder vi ett formulärelement med ett enktyps värde av multipart / form-data för att generera all kod för oss. Med hjälp av det här vissa attributet kan vi ange att formuläret innehåller binär data och det måste hanteras som sådant. En provform skulle se ut så här.
Men kom ihåg att vi fortfarande behöver skicka in ett antal parametrar till tjänsten, inklusive api-nyckeln, autentoken och metodens signatur. Hur gör vi det? Det är bara en fråga om att skapa ett dolt textfält och ändra sitt värde för att återspegla de korrekta värdena. Såhär:
Kom ihåg att samtidigt som du skapar MD5-hash för signatursträngen måste du ladda upp varje del av formuläret exklusive fotofältet. Detta inkluderar inmatningsknappens värde eftersom innehållet i hela formuläret postas till webbadressen. För ovanstående exempel skulle hashet vara beräknat som så:
var hash = MD5 (hemlig + "api_key" + apikey + "auth_token" + token + "submitUpload");
Du är inte helt begränsad till dessa argument. Uppladdnings API tar ett antal argument, inklusive titeln på fotot, dess titel och beskrivning. Om du ville att du kan lika lätt låta användaren ange alla dessa data tillsammans med sekretessinställningar som så:
En artikel om hur man arbetar med en tjänstens API skulle vara klart ofullständig utan att titta på några av de mest använda API-metoderna. Med det i åtanke är det några API-metoder som borde vara till stor hjälp oavsett om du skapar en mashup eller bara söker för att hämta dina egna data.
Kom ihåg att autentiserade samtal kräver giltiga värden för api_key, api_sig och auth_token parametrar att fungera medan vanliga samtal kanske eller inte kräver metodspecifika parametrar. Allt samtal kräver att api_key-parametern ska skickas in. Så om jag nämna samtalet krävs autentisering, är det faktum att samtalet kräver de andra argumenten implicit implicit. Argument som anges nedan är valfria om inte annat nämns. Metoder som returnerar en lista med data tar också en sida och per_page argument för att definiera sina namnnamn.
Jag har inkluderat svar från varje metod för att ge dig en uppfattning om de data som levereras tillbaka till oss. Jag har gått med JSON som svarformat eftersom de flesta devs jag jobbar med som JSON bättre än XML.
flickr.activity.userPhotos
Returnerar en lista över den senaste aktiviteten på foton som tillhör den uppringande användaren.
Argument: tidsram - Definierar tidsramen för att leta efter uppdateringar.
autentisering: Ja
Svar
"items": "item": "[" "typ": "foto", "id": "3728895285", "ägare": "40318902 @ N02", "eget namn": "lordtottuu", "hemligt" "dotter": 0, "notesold": 0, "notesold": 0, "notesold": 0, "notesold": 0, "notesold" "noter": 0, "visningar": 0, "faves": 0, "mer": 0, "aktivitet": "händelse": ["type": "kommentar", "commentid": "40298554- 3728895285-72157621628251433 "," user ":" 40318902 @ N02 "," användarnamn ":" lordtottuu "," dateadded ":" 1248131143 "," _content ":" Demo-bild för min kommande artikel om Net Tuts "] ], "sida": 1, "sidor": 1, "perpage": 10, "totalt": 1, "stat": "ok"
flickr.contacts.getList
Returnerar en lista med kontakter för den anropande användaren.
Argument: Filter - Argument för att filtrera bort listan. Giltiga värden inkluderar vänner, familj, både och varken.
autentisering: Ja
Svar
"kontakter": "sida": 1, "sidor": 1, "per_sida": 1000, "per sida": 1000, "totalt": 2, "kontakt": ["nsid": "7488445 @ N05 "," användarnamn ":" thegleek "," iconserver ":" 179 "," iconfarm ": 1," ignorerad ": 0," realname ":" Mike Poleski "," vän ":" 1 "," familj " : "0", "path_alias": null, "plats": ""] // Resten av kontakterna, "stat": "ok"
flickr.favorites.getList
Returnerar en lista med foton som är markerade favorit av en viss användare.
Argument: min_fave_date, max_fav_date - Självförklarande.
autentisering: Ja
Svar
"foton": "sida": "sidor": 1, "per sida": 100, "totalt": "3", "foto": ["id": "2332823355", "ägare" "53555705 @ N00", "hemlig": "e603be40a2", "server": "2333", "gård": 3, "titel": "Xbox 360 stilleben", "ispublic": 1, "isfriend": 0 , "isfamily": 0, "date_faved": "1248134938"] // Resten av bilderna, "stat": "ok"
flickr.people.getPublicPhotos
Hämta en lista med offentliga foton för den angivna användaren.
Argument: nsid [krävs] - ID för den anropande användaren, safe_search - Att blockera NSFW-innehåll.
autentisering: Nej
Svar
"foton": "sida": 1, "sidor": 1, "per sida": 100, "totalt": "15", "foto": ["id": "3728895285", "ägare" "40318902 @ N02", "hemlighet": "df6dfee053", "server": "3466", "gård": 4, "titel": "opac", "ispublic": 1, "isfriend": 0, "isfamily ": 0] // Resten av bilderna," stat ":" ok "
flickr.groups.getInfo
För att få information om en viss grupp.
Argument: group_id [krävs] - Gruppens ID för vilken du söker information.
autentisering: Nej
Svar
"id": "51035612836 @ N01", "iconserver": "1", "iconfarm": 1, "namn": "_content": "Flickr API", "beskrivning": "_content": sträng "A Flickr-grupp för Flickr API-projekt. Kör medvetenhet om Flickr API, projekt som använder det och de otroliga idéer som programmatiskt utsatta system producerar. Tänk Google API + Amazon API + Flickr API med lite GMail kastat in. Utvecklarna av Flickr påpekade med rätta att de vill hålla tekniska diskussioner direkt relaterade till API-en på postlistan. " , "medlem": "_content": "7775", "sekretess": objekt "_content": "3", "lang": null, "ispoolmoderated": 1, "gasspjäll" räkning ":" 3 "," läge ":" dag "," restriktioner ": objekt " 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
Extraherar EXIF-data för ett befintligt foto .
Argument: photo_id [krävs] - ID för fotot vars EXIF-data ska extraheras.
autentisering: Nej
Svar
"id": "2332823355", "hemligt": "e603be40a2", "server": "2333", "gård": 3, "exif": ["tagspace": "TIFF" "tagspaceid": 1, "tagg": 271, "etikett": "Gör", "rå": "_content": "Canon", "tagspace": "TIFF" "tagg": 272, "etikett": "Modell", "rå": "_content": "Canon EOS 350D DIGITAL" // Övriga exifdata], "stat": "ok"
flickr.photos.geo.getLocation
Returnerar latitud och longitud för den plats där ett visst foto togs.
Argument: photo_d [krävs] - ID för fotot vars plats ska vara känd.
autentisering: Nej
Svar
"id": objekt "id": sträng "229097925", "plats": objekt "latitud": -33.856874, "longitud": 151.214672, "noggrannhet": "16" , "plats": "_content": "Sydney", "place_id": "p50kaZyYAJx9BZHQ", "woeid": "1105779", "region": objekt "_content": "New South Wales", "place_id" : "puGzSeubAphuNnF2", "woeid": "2344700", "land": objekt "_content": "Australien", "place_id": "om3Zr2abAphqrm3jdA", "woeid": "23424748", "place_id" "p50kaZyYAJx9BZHQ", "woeid": sträng "1105779", "stat": sträng "ok"
flickr.photos.getFavorites
Returnerar en lista över personer som har markerat det överförda fotot som favorit.
Argument: photo_id [krävs] - ID för det aktuella fotot.
autentisering: Nej
Svar
"photo": "person": ["nsid": "39011391 @ N06", "användarnamn": "derek1960", "favedate": "1243834286", // Resten av bilderna] : "229097925", "hemlighet": "13a21546fb", "server": "61", "gård": 1, "sida": 1, "sidor": 2, "perpage": 10, "totalt" 18 "...," stat ":" ok "
flickr.places.getTopPlacesList
Returnerar en lista över de 100 mest märkta platserna för en dag.
Argument: place_type_id [krävs] - Numeriskt ID för en plats för att definiera hur man kluster bilder.
autentisering: Nej
Svar
"places": objekt "totalt": nummer100, "plats": ["place_id": "4KO02SibApitvSBieQ", "woeid": "23424977", "latitud": "48.890", "longitud": "-116.982 "," place_url ":" / United + States "," place_type ":" land "," place_type_id ":" 12 "," _content ":" United States "," photo_count ":" 23654 ", // Vila av de 99 länderna], "date_start": 1248048000, "date_stop": 1248134399, "stat": "ok"
flickr.tags.getHotList
Returnerar en lista över mest använda taggar under en viss tidsperiod.
Argument: period - Anger vilken period för att få taggar. räkna - Anger hur många taggar som ska returneras i svaret.
autentisering: Nej
Svar
"period": "dag", "count": 20, "tag": ["score": "100", "_content": "sundaystreets", "score" "," _content ":" happymondayblues ", " score ":" 100 "," _content ":" melbourneopenhouse2009 "]," stat ": sträng" ok "
I den här inledande delen av serien tittade vi på hur man arbetar med Flickr API, inklusive hur man hämtar offentlig och privat data, autentiserar med API och hur man laddar upp data till tjänsten. Vi kollade också på några av de mest använda API-metoderna tillsammans med deras JSON-svar för att bättre förstå strukturen hos de data som API skickar tillbaka.
Vilket API är täckt nästa är helt upp till dig. Här, på Net Tuts, tillgodoser vi den populära efterfrågan och så ska vi låta er läsarna bestämma vilken tjänstes API som ska skrivas om nästa. I din kommentar nedan, lämna namnet på tjänsten och API-gränssnittet, om det behövs. Vi omfattade REST i den här artikeln, men vi skulle gärna täcka SOAP-baserade eller XML-RPC-baserade API-skivor om tillräckligt många människor vill ha det.
Frågor? Trevliga saker att säga? Kritik? Klicka på kommentarfältet och lämna mig en kommentar. Lycklig kodning!
