API për Zhvilluesit

Të gjithë zhvilluesit që duan të integrojne diskutimet e Hap në aplikacionet e tyre, qofshin web apo jo, mund të përdorin API-n tonë. Struktura është aq ë thjeshtë sa nuk do ju marrë më shumë se disa minuta para se të filloni implementimin. Mjafton që të dërgoni një kërkesë GET në një URL të caktuar dhe të lexoni përgjigjen në format JSON.

Publike vs Private

Duke qenë se shumë prej veprimeve brenda Hap mund të kryhen vetëm si anëtar i regjistruar, edhe API është e ndarë në 2 seksione. Pjesa publike mund të përdoret nga kushdo, pa qenë e nevojshme të regjistrohet, por është e limituar. Ndërsa ajo private ofron më tepër, por kërkon një Çelës API për të kryer identifikimin dhe tërheqjen e të dhënave që i përkasin atij anëtari.

Çelësi API ofrohet pasi të regjistroheni. Mund ta gjeni në menunë e anetarit, të titulluar "Çelësi API".

Kërkesa

Kërkesa është një GET e thjeshtë në një URL të caktuar (shpjeguar më poshtë). Shumica e gjuhëve të programimit apo librarive ofrojnë mënyra të lehta për ta kryer këtë veprim.

Përgjigjia

Përgjigjia është një JSON, me një format të caktuar që krahas të dhënave, tregon statusin dhe mesazhin. JSON është një format popullor, që lexohet thjeshtë nga praktikisht çdo gjuhë programimi moderne, me funksionalitetet bazë apo me module të jashtme. Një shembull i një pergjigjeje shfaqet më poshtë.

{"statusi":"10","data":[...],"mesazhi":"OK"}

Ndërkohë që mesazhi mund të jetë një informues i mirë për probleme, nuk është edhe aq i përdorshem për t'i identifikuar ato në formë programatike. Për këtë janë kodet e statusit, të cilat i kemi mbajtur në minimum. Kjo teknikë edhe e lehtëson leximin e përgjigjeve sepse gjithçka ju duhet ndodhet në të, pa qenë nevoja të eksploroni statuset HTTP dhe të ngjashëm. Më poshtë janë kodet e mundshme që një përgjigje mban.

10 : Kërkesa u egzekutua me sukses.
0 : Kërkesa nuk është e plotë. Nuk përmban çelës API apo ID.
1 : Kërkesë e pa saktë. Nuk u gjet çelesi API apo ID-ja e dhënë.

Diskutimet e Nxehta (Publike)

Kthen një listë diskutimesh që nga sistemi janë përcaktuar si "të nxehta". Zakonisht, janë diskutimet me numër më të madh vlerësimesh.

http://www.hap.al/api/nxehta

Kthehet një listë me maksimalisht 15 diskutime të nxehta. Për të vendosur manualisht se ku fillon dhe sa zgjat lista, mund të shtoni 2 elemente në URL.

http://www.hap.al/api/nxehta/fillimi/zgjatja

Fillimi dhe zgjatja janë numra që vendosin së në cilin diskutim do fillojë përgjigja dhe sa diskutime duhen kthyer. Kjo është më tepër e vlefshme në raste kur doni të implementoni sistem faqesh, apo të ndryshoni numrin e rezultateve të kthyer.

Për shembull, URL-ja më poshtë kthen një listë që fillon nga rezultati i pestë dhe se duhen kthyer 20 diskutime.

http://www.hap.al/api/nxehta/5/20

I njëjti koncept për fillimin dhe zgjatjen përdoret edhe në disa prej kërkesave që vijojnë më poshtë. Për mos tu përsëritur, do të përcaktohet vetëm nëse kerkesa i suporton ose jo.

Një shembull i të dhënave të kthyera shfaqet më poshtë. Formati është konsistent me të gjitha metodat e tjera.

{
"ID":"1",
"kategoria":"Humor",
"autori":"Jim Carrey",
"titulli":"Nje titull humoristik",
"trupi":"Nje trup akoma me humoristik",
"foto":"foto.jpg",
"videoYoutube":"",
"dataHapjes":"2012-12-12 00:00:00",
"pergjigjaFundit":"2012-12-12 00:00:12",
"vleresime":"150",
"shikime":"823"
}

Diskutimet e Fundit (Publike)

Kthen një listë diskutimesh, të renditura sipas datës së hapjes. Limitohet në 15 diskutime dhe suporton vendosjen e fillimit dhe zgjatjes.

http://www.hap.al/api/fundit/[fillimi]/[zgjatja]

Diskutim i Caktuar (Publike)

Kthen të dhënat e një diskutimi të vetëm, që përcaktohet duke kaluar ID-në. Për të marrë ID-në e një diskutimi, duhet ta vizitoni dhe ta gjeni ne URL. Zakonisht është e formës:

http://www.hap.al/diskutimi/(ID)/(titulli)

Me të marrë ID-në, mund të dërgoni një kërkesë në formën më poshtë.

http://www.hap.al/api/diskutimi/ID

Do të kthejë status 0 nëse nuk vendosni një ID ose status 1 nëse nuk gjendet asnjë diskutim.

Përgjigjet e një Diskutimi (Publike)

Kthen një listë me përgjigjet në një diskutim të caktuar. Përsëri nevojitet ID-ja e diskutimit, që mund të merret si në rastin e "Diskutimit te Caktuar". Limitohet në 15 përgjigje dhe suporton vendosjen e fillimit dhe zgjatjes.

http://www.hap.al/api/pergjigjet/ID/[fillimi]/[zgjatja]

Do të kthejë status 0 nëse nuk vendosni një ID ose status 1 nëse nuk gjendet asnjë diskutim. Duhet të keni parasysh që mund të kthehet një përgjigje bosh me status 10 (e saktë). Nuk do të thotë se ka patur problem, por se diskutimi nuk ka akoma asnjë përgjigje.

Kërkimi (Publike)

Kthen një listë me diskutimet dhe/ose përgjigjet që përmbajnë tekstin që po kërkoni. Limitohet në 15 rezultate dhe mund të përcaktohet fillimi dhe zgjatja.

http://www.hap.al/api/kerko/teksti+kerkimit

Do të kthejë status 0 nëse kërkimi nuk është vendosur. Mbani mend që duhet enkoduar teksti i kërkimit që rezultatet të jenë sa më të sakta. Suporton operatorët boolean sipas kërkimit FULLTEXT te MySQL. Përgjigja mund të jetë bosh nëse kërkimi nuk prodhon asnjë rezultat.

Diskutimet ku keni komentuar (Private)

Kthen diskutimet ku ju, si anëtar i regjistruar, keni dhënë të paktën një përgjigje. Kërkon çelës API, kthen 15 rezultate dhe mund të përcaktohet fillimi dhe zgjatja.

http://www.hap.al/api/komentuar/celesi_API/[fillimi]/[zgjatja]

Do të kthejë status 0 nëse nuk është vendosur një çelës API ose 1 nëse çelësi API nuk është i saktë. Pergjigja mund të jetë bosh nëse nuk keni komentuar në asnjë diskutim.

Diskutimet ku jeni abonuar (Private)

Kthen diskutimet ku jeni abonuar. Kërkon çelës API, kthen 15 rezultate dhe mund të përcaktohet fillimi dhe zgjatja.

http://www.hap.al/api/abonuar/celesi_API/[fillimi]/[zgjatja]

Do të kthejë status 0 nëse nuk është vendosur një çelës API ose 1 nëse çelësi API nuk është i saktë. Përgjigja mund të jetë bosh nëse nuk jeni abonuar në asnjë diskutim.

Diskutimet dhe përgjigjet e anëtarëve të ndjekur (Private)

Kthen diskutimet dhe përgjigjet e anëtarëve që ndiqni. Kerkon çelës API, kthen 15 rezultate dhe mund të përcaktohet fillimi dhe zgjatja.

http://www.hap.al/api/ndjekur/celesi_API/[fillimi]/[zgjatja]

Do të kthejë status 0 nëse nuk është vendosur një çelës API ose 1 nëse çelësi API nuk është i saktë. Përgjigja mund të jetë bosh nëse nuk jeni duke ndjekur ndonjë anëtar apo nëse anëtarët që po ndiqni nuk kanë hapur diskutime apo përgjigje.

Diskutimet Tuaja (Private)

Kthen diskutimet që ju keni hapur. Kërkon çelës API, kthen 15 rezultate dhe mund të përcaktohet fillimi dhe zgjatja.

http://www.hap.al/api/miat/celesi_API/[fillimi]/[zgjatja]

Do të kthejë status 0 nëse nuk është vendosur një çelës API ose 1 nëse çelësi API nuk është i saktë. Përgjigja mund të jetë bosh nëse nuk keni hapur akoma një diskutim.

Informacione Personale (Private)

Kthen informacionet personale, pa përfshirë të dhëna sensitive, që keni vendosur në profilin tuaj. Kërkon çelësin API.

http://www.hap.al/api/anetari/celesi_API

Do të kthejë status 0 nëse nuk është vendosur një çelës API ose 1 nëse çelësi API nuk është i saktë.

Fotot e Diskutimeve

Hap i lejon anëtarët të ngarkojnë foto në diskutime dhe si ç'mund të shihni nga përgjigjet e kërkesave ku kthehen informacione rreth diskutimeve, foto jepet thjeshtë si emër skedari. Ne nuk e inkurajojmë përdorimin direkt të fotove, sepse mund të sjellë trafik të pa-parashikuar dhe të na shkaktojë probleme në server. Megjithatë, nëse e shihni patjetër të domosdoshme, nuk ja u pengojmë. Thjeshtë do i monitorojmë me kujdes kërkesat dhe mund të bllokojmë përdorimet intensive.

Duke supozuar se diskutimi ka një foto me emër skedari "foto.jpg", URL-të përmes të cilave mund të aksesoni foton janë si më poshtë.

http://www.hap.al/stash/photos/foto.jpg
http://www.hap.al/stash/photos/thumb_foto.jpg

E para është foto me madhësinë origjinale, ndërsa e dyta është foto e zvogëluar dhe e përpunuar. Do të doni të përdorni të dytën (thumb_foto.jpg) sepse e para zakonisht është me përmasa të mëdha.

Fotot e Profilit

Anëtarët mund të vendosin foto profili për të identifikuar veten dhe këto foto janë te aksesueshme permes API-t, në disa versione. Ashtu si me fotot e diskutimeve, edhe këtu nuk e inkurajojme përdorimin direkt dhe do të monitorojmë trafikun.

Duke supozuar se anëtari ka një foto me emër skedari "foto.jpg", URL-të më poshtë ju tregojnë se si mund të aksesoni versionet e ndryshme.

http://www.hap.al/stash/profile/foto.jpg
http://www.hap.al/stash/profile/big_foto.jpg
http://www.hap.al/stash/profile/med_foto.jpg
http://www.hap.al/stash/profile/mini_foto.jpg

Duke i dërguar mesazh: Ylli Panariti