302.hu - Fejlesztői eszközök
API - Alkalmazás Programozható Interfész
API használatról általában
A 302.hu API-t kizárólag regisztrált felhasználók használhatják. Az API célja, hogy – akár – automatizáltan is használni lehessen az oldal bizonyos szolgáltatásait.
API kérések
Az API kéréseket programozási nyelvtől függetlenül lehet igénybe venni. Lényeg, hogy POST kérést intézzünk a szerver felé, a megadott URL-re. A POST kérés egyrészt tartalmazza magát a kérést, másrészt egy publikus kulcsot, ami azonosítja a kérés küldőjét (ez az azonosítás még nem egyenértékű a hitelesítéssel).
A kérés (enc_request), a felhasználó titkos kulcsával titkosított, a publikus kulcs nyilvános, nincs titkosítva. A beérkező adatokból a szerver, a kapott publikus kulcs segítségével kibontja a titkosított kérést, majd feldolgozza azt. Amennyiben nem lehet azonosítani a publikus kulccsal a küldőt, vagy a kérés kibontása nem jár sikerrel, úgy egy hiba üzenetet ad vissza a szerver.
{ "result":"error", // Az eredmény sikertelen "data":"err_no_valid_request" // A hiba kódja }
A kérések titkosított része minden esetben a következő felépítést kapja:
- pHash: A publikus kulcs md5 hashe, a kérés kibontása után ezzel validáljuk a kérést.
- request: A kérés típusa (pl.: freshList)
- action: A kérés akciója (pl.: myList), ezt alapesetben nem kötelező megadni, ilyenkor a kérés alap akciója hívódik meg.
- params: A kéréshez intézett paraméterek tömbje.
API kérések eredménye
Minden API kérés eredménye egy JSON string, ami kötelezően a következő felépítést kapja:
result: Az eredmény sikerességét jelzi minden esetben.
- success: Sikeres végrehajtás
- error: Sikertelen végrehajtás
type: Az eredmény – data tag - típusa
- html: HTML kód kerül vissza küldésre eredményképpen.
- json: JSON stringet küld vissza a szerver eredményül.
- redirect: A szerver egy átirányítás URL-jét küldi válaszképp.
data: Az eredmény.
redirect: Az átirányítási cím, amennyiben a type tag redirect típusú.
Példa egy sikeres link rövidítés eredményére
{ "result":"success", // Az eredmény sikeres "data":{ // Az eredmény tömbje "shortUrl":"302.hu\/_R", // Az elkészült rövidítés URL-je "url":"http:\/\/www.pelda-domain.hu", // A rövidítendő URL "expire_date":"2013-06-29 17:24:35", // Az elkészült rövidítés lejárata "passworded":1 // Az elkészült rövidítés jelszóvédett }, "redirect":"", // Nincs átirányítási URL "type":"json" // Az eredmény típusa JSON string }
Az API kérések listája
Az API kérések listájánál a kettőspont előtt látható a kérés neve, a kettőspont után pedig a kéréshez tartozó akció
freshList:index
A freshList alapértelemezett index akció hívásával, lekérdezhető a legfrissebb rövidítések listája.
Használható paraméterek
- limit: [int] A lekérdezendő lista hossza, max. 50
Példa a request tömbre (PHP):
$request = array(); // Ez egy validáló paraméter, a publikus kulcs md5 hash-e $request['pHash'] = md5($publicKey); // A kérés tipusa, ez határozza meg, hogy url vagy jegyzet rövidítés lesz $request['request'] = 'freshList'; // Ha a kérésnek van további akciója, akkor itt tudod megadni, alapesetben 'index' legyen $request['action'] = 'index'; // A kérés paraméterei, minden requestnek saját paraméterlistája van $request['params'] = array( 'limit'=>'2'); // a lekért lista hossza
Példa válasz a kérésre:
{ "result":"success", // a kérés sikeresen elkészült "data":{ // az eredmény tömb "items":[ // a kapott elemek listája { "title":"teszt jegyzet c\u00edme", // az elem címe (jegyzet cím, vagy link) "when":"2013-06-30 09:38:25", // mikor készült a rövidítés "url":"_Y", // a rövid link "type":"note", // a rövidítés típusa (note vagy url) "is_adult":"0" // 18+ tartalom-e },{ "title":"www.123.hu", "when":"2013-06-30 09:35:08", "url":"_X", "type":"url", "is_adult":"0" } ] }, "redirect":"", "type":"json" }
freshList:myList
A freshList myList akció hivással a felhasználó saját rövidítéseinek listája kérhető le.
Használható paraméterek
- limit: [int] A lekérdezendő lista hossza
- offset: [int] A lekérdezendő lista offsetje
Példa a request tömbre (PHP):
$request = array(); // Ez egy validáló paraméter, a publikus kulcs md5 hash-e $request['pHash'] = md5($publicKey); // A kérés tipusa, ez határozza meg, hogy url vagy jegyzet rövidítés lesz $request['request'] = 'freshList'; // Ha a kérésnek van további akciója, akkor itt tudod megadni, alapesetben 'index' legyen $request['action'] = 'myList'; // A kérés paraméterei, minden requestnek saját paraméterlistája van $request['params'] = array( 'limit'=>'2', // a lekért lista hossza 'offset'=>'0'); // a lekért lista oldala
Példa válasz a kérésre:
{ "result":"success", // a kérés sikeresen elkészült "data":{ // az eredmény tömb "items":[ // a kapott elemek listája { "title":"http:\/\/www.pelda-domain.hu", // az elem címe (jegyzet cím, vagy link) "when":"2013-06-30 09:39:03", // mikor készült a rövidítés "url":"_Z", // a rövid link "type":"url", // a rövidítés típusa (note vagy url) "is_adult":"1", // 18+ tartalom-e "is_passworded":"1", // jelszóvédett-e "is_public":"0" // publikus-e },{ "title":"teszt jegyzet c\u00edme", "when":"2013-06-30 09:38:25", "url":"_Y", "type":"note", "is_adult":"0", "is_passworded":"0", "is_public":"1" } ], "itemsNum":"12" // a felhasználó összes rövidítésének száma }, "redirect":"", "type":"json" }
noteShorter:index
A noteShorter felelős a jegyzetek rövidítéséért, a noteShorter és az urlShorter megegyező működési logikával működnek.
Használható paraméterek
- note: [string] A rövidítendő jegyzet tartalma.
- note_title: [string] A rövidítendő jegyzet címe (nem kötelező).
- expire_date:[string] A rövidítés lejárata
- 1h: A rövidítéstől számított 1 órán keresztül elérhető a rövidítés.
- 1d: A rövidítéstől számított 1 napon keresztül elérhető a rövidítés.
- 1w: A rövidítéstől számított 1 héten keresztül elérhető a rövidítés.
- 1m: A rövidítéstől számított 1 hónapon keresztül elérhető a rövidítés.
- 6m: A rövidítéstől számított fél éven keresztül elérhető a rövidítés.
- inf: Bármeddig elérhető a rövidítés.
- psswd_hash:[string, md5 hash] Ha a rövidítést jelszóvédetté szeretnénk tenni, akkor itt kell közölni a jelszó MD5 hash-t. Jelszó beállítás esetén az is_public opció automatikusan felül lesz bírálva. A jelszóval védett rövidítések sosem publikusak.
- is_public:[int] Amennyiben a rövidítést publikusá szeretnénk tenni, ez esetben bárki által látható lesz a rövidítés. Ha jelszavas rövidítést készítünk, az is_public opció automatikusan felül lesz írva.
- is_adult:[int] Ha a rövidítendő tartalom 18 éven felüleknek szánt, akkor ezzel az opcióval jelezhetjük ezt.
Példa a request tömbre (PHP):
$request = array(); // Ez egy validáló paraméter, a publikus kulcs md5 hash-e $request['pHash'] = md5($publicKey); // A kérés tipusa, ez határozza meg, hogy url vagy jegyzet rövidítés lesz $request['request'] = 'noteShorter'; // Ha a kérésnek van további akciója, akkor itt tudod megadni, alapesetben 'index' legyen $request['action'] = 'index'; // A kérés paraméterei, minden requestnek saját paraméterlistája van $request['params'] = array( 'note'=>'teszt jegyzet szövege....', // a rövidítendő jegyzet tartalma 'note_title'=>'teszt jegyzet címe', // a rövidítendő jegyzet címe 'expire_date'=>'1h', // a lejárati idő 1 óra lesz 'psswd_hash'=>'', // nem lesz jelszóvédett a rövidítés 'is_public'=>'1', // publikus lesz a jegyzet 'is_adult'=>'0'); // 18+ tartalommal nem rendelkezik
Példa válasz a kérésre:
{ "result":"success", // a kérés sikeresen elkészült "data":{ "shortUrl":"302.hu\/_T", // az elkészült rövid link "expire_date":"2013-06-30 00:18:50", // a rövidítés lejárata, eddig érvényes "passworded":0 // jelszóval védett-e, ez esetben nem }, "redirect":"", "type":"json"}
urlShorter:index
Az urlShorter készíti el a link rövidítéseket, az urlShorter és a noteShorter megegyező működési logikával működnek.
Használható paraméterek
- url: [string] A rövidítendő URL (http://www.pelda-domain.hu)
- expire_date:[string] A rövidítés lejárata
- 1h: A rövidítéstől számított 1 órán keresztül elérhető a rövidítés.
- 1d: A rövidítéstől számított 1 napon keresztül elérhető a rövidítés.
- 1w: A rövidítéstől számított 1 héten keresztül elérhető a rövidítés.
- 1m: A rövidítéstől számított 1 hónapon keresztül elérhető a rövidítés.
- 6m: A rövidítéstől számított fél éven keresztül elérhető a rövidítés.
- inf: Bármeddig elérhető a rövidítés.
- psswd_hash:[string, md5 hash] Ha a rövidítést jelszóvédetté szeretnénk tenni, akkor itt kell közölni a jelszó MD5 hash-t. Jelszó beállítás esetén az is_public opció automatikusan felül lesz bírálva. A jelszóval védett rövidítések sosem publikusak.
- is_public:[int] Amennyiben a rövidítést publikusá szeretnénk tenni, ez esetben bárki által látható lesz a rövidítés. Ha jelszavas rövidítést készítünk, az is_public opció automatikusan felül lesz írva.
- is_adult:[int] Ha a rövidítendő tartalom 18 éven felüleknek szánt, akkor ezzel az opcióval jelezhetjük ezt.
Példa a request tömbre (PHP):
$request = array(); // Ez egy validáló paraméter, a publikus kulcs md5 hash-e $request['pHash'] = md5($publicKey); // A kérés tipusa, ez határozza meg, hogy url vagy jegyzet rövidítés lesz $request['request'] = 'urlShorter'; // Ha a kérésnek van további akciója, akkor itt tudod megadni, alapesetben 'index' legyen $request['action'] = 'index'; // A kérés paraméterei, minden requestnek saját paraméterlistája van $request['params'] = array( 'url'=>'http://www.pelda-domain.hu', // a rövidítendő url 'expire_date'=>'1h', // a lejárati idő 1 óra lesz 'psswd_hash'=>md5('jelszo'), // jelszóvédett lesz a rövidítés 'is_public'=>'0', // nem lesz publikus 'is_adult'=>'1'); // 18+ tartalommal rendelkezik
Példa válasz a kérésre:
{ "result":"success", // a kérés sikeresen elkészült "data":{ "shortUrl":"302.hu\/_Z", // az elkészült rövid link "url":"http:\/\/www.pelda-domain.hu", // a rövidített link "expire_date":"2013-06-30 10:39:03", // a rövidítés lejárata, eddig érvényes "passworded":1 // jelszóval védett-e, ez esetben igen }, "redirect":"", "type":"json" }
API tesztelése
Amennyiben csak tesztelni szeretné az API-t, úgy az API kérés útvonal végére kell illeszteni a /test paramétert.
// Az API kérés teszt útvonala $_api_url = 'http://302.hu/*api/test';
Az API tesztelésnek csak akkor van hatása, ha a kérés nem csak adatlekéréssel jár, teszt esetén nem történik adat bejegyzés, csak a kérés ellenőrzése történik meg. Így, ha a kérés megfelelő, akkor csak egy teszt eredményt közöl a szerver.
Példa válasz a kérésre (urlShorter esetén):
{ "result":"success", // a kérés "data":{ "testRequest":true, // teszt kérés, ez minden teszt kérés esetén megjelenik "shortUrl":"302.hu\/_test", // teszt kérés esetén mindig _test a rövidített url "url":"http:\/\/www.pelda-domain.hu", // a rövidítendő link (megegyezik az éles kéréssel) "expire_date":"2013-06-30 14:05:53", // a rövidítés lejárata (megegyezik az éles kéréssel) "passworded":1 // jelszóval védett-e a rövidítés (megegyezik az éles kéréssel) }, "redirect":"", "type":"json" }
API használata - PHP példa
/** * 302.hu API kérést készítő példa * 2013-06-26 v1.0 * Szentgyörgyi János - info@dynamicart.hu * * API sugó és leírás: http://302.hu/*fejlesztoknek */ // A felhasználó publikus kulcsa, ez azonosítja a kérésnél a felhasználót $publicKey = 'ce6175f9c1b1aa5abfc5ae8663403463'; // A felhasználó titkus kulcsa, ezzel történik a kérések titkosítása $secretKey = '0e557b830b03b86f2cea0419e10bff6151c88bf7118a9'; // Az API kérés útvonala $_api_url = 'http://302.hu/*api'; // A kérés előkészítése $request = array(); // Ez egy validáló paraméter, a publikus kulcs md5 hash-e $request['pHash'] = md5($publicKey); // A kérés tipusa, ez határozza meg, hogy url vagy jegyzet rövidítés lesz $request['request'] = 'urlShorter'; // Ha a kérésnek van további akciója, akkor itt tudod megadni, alapesetben 'index' legyen $request['action'] = 'index'; // A kérés paraméterei, minden requestnek saját paraméterlistája van $request['params'] = array( 'url'=>'http://www.pelda-domain.hu', 'expire_date'=>'1h', 'psswd_hash'=>md5('jelszo'), 'is_public'=>'0', 'is_adult'=>'1'); // A kérés feldolgozása $request = utf8_encode(json_encode($request)); $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_256, MCRYPT_MODE_ECB); $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND); $theKey = pack('H*', $secretKey); $enc_request = mcrypt_encrypt(MCRYPT_RIJNDAEL_256, $theKey, $request, MCRYPT_MODE_ECB, $iv); $enc_request = base64_encode($enc_request); // Az API kérés tényleges paraméter tömbje $params = array(); // Az elkódolt kérés, ez tartalmazza mit is szeretnénk kérni $params['enc_request'] = $enc_request; // A publikus kulcs, ezzel fog azonosítani minket a szerver $params['public_key'] = $publicKey; // A cUrl kérés beállítása $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $_api_url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, count($params)); curl_setopt($ch, CURLOPT_POSTFIELDS, $params); // A cUrl kérés meghívása $result = curl_exec($ch); // Az eredmény json dekódolása $result = @json_decode($result, true); // Az eredmény kiírása var_dump($result);
Lehetséges hibakódok
- err_invalid_url: Kérlek valós címet adj meg
- err_already_shorturl: Már rövidített címet nem rövidítünk tovább
- err_empty_note: Kérlek írd be a szöveget
- err_sql_error_try_again: Belső hiba történt, kérlek próbálkozz újból!