[bejelentkezés] | [segítség] | [kapcsolat] |

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!