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!