Průvodce - API

Autorizace Netquest API

Pro potřeby mobilních a desktopových aplikací bylo do Netquest API implementováno OAuth rozšíření pojmenované xAuth (řešení známé z API Twitteru). Implementace oAuth protokolu v různých jazycích se nachází na http://oauth.net/code/.

Získání klíče access_token

Pro přihlášení do API použitím xAuth je zapotřebí mít klíče consumer_key a consumer_secret.
Požadavek musí být zaslán na adresu

https://www.netquest.cz/api/xauth/access-token

předáním následujících dat použitím metody POST:

$params = array(
   //uživatelské jméno, pro které má být token získán
   'x_auth_username' => 'petr.novak@netquest.cz', 
   //enkódované heslo pro uživatele, pro kterého má být token získán
   'x_auth_md5_password' => md5('vaseheslo')
   //tento parametr musí mít stejnou hodnotu
   'x_auth_mode' => 'client_auth'
);

Hlavička Authorization musí mít následující podobu

OAuth realm="", 
oauth_version="1.0", 
oauth_signature_method="HMAC-SHA1", 
oauth_consumer_key="79a44132c8fed1c2a15778941531c6a804ec60b2b", 
oauth_timestamp="1322083695", 
oauth_nonce="0790a4299979bbca1ee2882807448cd304ecd656f", 
oauth_signature="RudpQeTM8sHPg5EGxtm4N6hfkJ8%3D"

Po úspěšném autorizování budou jako odpověď vráceny oauth_token a oauth_token_secret.
V tomto okamžiku by měla aplikace odstranit data uživatele (x_auth_username a x_auth_md5_password) a použít standardní oAuth procedury pro oveření na serveru.

Ukázka

$consumerKey = '79a44132c8fed1c2a15778941531c6a804ec60b2b';
$consumerSecret = '18f37873635e0f43dd81f69f2ecfba59';

$params = array(
	'x_auth_username' => 'petr.novak@netquest.cz',
	'x_auth_md5_password' => md5('vaseheslo'),
	'x_auth_mode' => 'client_auth'
);

$consumer = new Netquest_Api_Client($consumerKey, $consumerSecret);
$consumer->setUri('/xauth/access-token');
$consumer->setParams($params);
$result = $consumer->request();

Zend_Debug::dump($result);
/**
 * {
 *    "oauth_token":"54dbb76fe456b2d7126ccf232e37481e04ecd5fef",
 *    "oauth_token_secret":"951afe99dc9c8215b3097706e9648dba",
 *    "id_user":"9456"
 * }
 */

Aplikace klienta by měla mít token a token_secret, které společně s consumer_key a consumer_secret umožňují správné ověření.

Ukázka – Zasílání požadavku jménem uživatele

Cíl: Získání seznamu respondentů z konkrétního dotazníku

Pro tento účel budeme používat oauth_token a oauth_token_secret

Z dotazníku ID=1234 získáme seznam respondentů, kteří vyplnili dotazník dne 1. července, 2011 (2011-07-01).
Dodatečně, máme zájem pouze 10 respondentů.

Pro získání seznamu respondentů s výše uvedenými parametry je nutné použít operaci vyhledávání respondentů, dostupnou na

https://www.netquest.cz/api/respondents/search/:id

Požadavek bude odeslán použitím metody POST za účelem předání parametrů hledání. Dodatečné parametry budou potřeba také pro správné vykonání OAuth/xAuth požadavku. Všechny potřebné parametry jsou uvedeny níže.

Post body – date_survey_answer=2011-07-01&limit=10
oauth_consumer_key – 524c9e8f94b8eb676b95e94c59a844df04ec60cc0
oauth_nonce – oElnnMTQIZvqvlfXM56aBLAf5noGD0AQR3Fmi7Q6Y
oauth_signature_method -HMAC-SHA1
oauth_token – 14ee78ef86d8cca7a1a0661e290a76fa04ece90e9
oauth_timestamp -1272325550
oauth_version – 1.0

Následně vytvoříme signature base string dle stejných pravidel jako byly použity pro získání tokenu.

POST&https%3A%2F%2Fwww.netquest.cz%2Fapi%2Frespondents%2Fsearch%2F1234&
date_survey_answer%3D2011-07-01%26limit%3D10%26oauth_consumer_key%3D
524c9e8f94b8eb676b95e94c59a844df04ec60cc0%26oauth_nonce%3D
82d06397567e5fe1fcc7f000d35f07be04ed10783%26oauth_signature_method%3DHMAC-SHA1%26
oauth_timestamp%3D1322321795%26oauth_token%3D14ee78ef86d8cca7a1a0661e290a76fa04ece90e9%26
oauth_version%3D1.0

Další krok je vytvoření šifrovacího klíče pro generování podpisu pomocí oauth_consumer_secret a oauth_token_secret

07d740ac3613874f9528c3eab0279b98&ab8b78bbebb38b76f444c8a2ddf162ff

Použitím šifrovacího klíče ‚podepíšeme‘ signature base string. Výsledkem dostaneme:

JWrgkCsKm3OTpEQR5RI7kmtlpco%3D

Poté vytvoříme HTTP autorizační hlavičku Authorization. Samozřejmě, všechny tyto hodnoty musí být enkódovány (enkódovaná URL)

OAuth realm=""
oauth_nonce="oElnnMTQIZvqvlfXM56aBLAf5noGD0AQR3Fmi7Q6Y", 
oauth_signature_method="HMAC-SHA1", 
oauth_timestamp="1272325550", 
oauth_consumer_key="524c9e8f94b8eb676b95e94c59a844df04ec60cc0", 
oauth_token="14ee78ef86d8cca7a1a0661e290a76fa04ece90e9", 
oauth_signature="JWrgkCsKm3OTpEQR5RI7kmtlpco", 
oauth_version="1.0"

Posledním prvkem je provedení POST požadavku na Netquest API (koncový bod) a držet palce, aby všechno pracovalo správně :-).
Po úspěšném vykonání požadavku bychom měli obdržet následující odpověď:

{
	"total":"20",
	"list":[{
		"id":100824,
		"token":"549E56",
		"date_token_generate":"2011-11-25 22:27:42",
		"date_invitaion_send":null,
		"date_survey_open":null,
		"date_survey_answer":null,
		"email":"petr.novak@netquest.cz",
		"label1":"Petr",
		"label2":"Novak",
		"label3":"774 700 800",
		"label4":"",
		"label5":"",
		"answer_postponed":null
	},{
		...
	}]
}

Podepisování HTTP požadavku

Všechny OAuth 1.0 požadavky používají stejný základní algoritmus pro vytváření řetězec podpisu (signature base string) a vytváření podpisu.

Vytvoření signature base string je jedna z nejnáročnějších částí OAuth standardu.
Text tvoří následující části:

  1. použitý název metody (GET nebo POST)
  2. link-character ampersand ("&")
  3. enkódovaná URL s adresou operace, např. https://www.netquest.cz/api/surveys
  4. link-character ampersand ("&")
  5. parametry zaslané prostřednictvím POST požadavku a OAuth parametry nezbytné pro ověření požadavku.

Výše uvedené parametry (POST i OAuth) musí být řazeny v lexikografickém uspořádání.
Nejprve však musíme seřadit parametry podle klíče a pak podle hodnoty (v případě několika klíčů stejného názvu v tom samém HTTP požadavku).

Oba parametry a hodnoty musí být enkódované (urlencode).
Nachází-li se v hodnotě parametru mezera, měla by být odeslána jako %20

Namísto znaku pro rovná se "=" (relace klíč/hodnota) by měla být použita enkódovaná podoba – "%3D".
Hodnota každého parametru (klíč/hodnota) by měla být spojena enkódovaným & (ampersand) – "%26".

Výše uvedený algoritmus může být předložen jako pseudo-kód zobrazený níže:

httpMethod + "&" +
  url_encode(  base_uri ) + "&" +
  sorted_query_params.each  { | k, v |
      url_encode ( k ) + "%3D" +
      url_encode ( v )
  }.join("%26")

Bez ohledu na to, jaký typ žádosti provádíte, pravidla generování signature base string jsou vždy stejná

Netquest API vyžaduje OAuth/xAuth podepsání požadavků s HMAC-SHA1 algoritmem

Slovník

  • oauth_nonce – Jedinečný identifikátor každého HTTP požadavku generovaného aplikací klienta.
    Netquest API umožňuje použít jednu hodnotu oauth_nonce pro jeden požadavek.
    Cílem tohoto je eliminovat opakující se volání stejného požadavku
  • oauth_timestamp – Celé číslo představující počet sekund, které uplynuly od 1. ledna 1970.
    Hodnota klientova timestampu se nemůže lišit od hodnoty timestampu serveru o více než 600 sekund (10 minut)
    Je-li rozdíl větší, HTTP požadavek bude ignorován.
  • signature base string – „Sestavený“ text, podepsán pomocí šifrovacího klíče pro generování podpisu HTTP požadavku – oauth_signature
    Příklad vytvoření podpisu je popsán v části Podepisování HTTP požadavku
  • encryption key – Text (řetěze) použitý jako „tajný klíč“ pro podepisování HTTP požadavků.
    Podle OAuth 1.0 je standardu je šifrovací klíč vypočítáván podle následujícího algoritmu:

    url_encode( consumer_secret ) + "&" +
    url_encode( oauth_token_secret || nil )

    Některé z požadavků OAuth vyžadují použití oauth_token_secret, zatímco ostatní nikoliv.

    Šifrovací klíč je vždy složen z hodnot consumer_secret a oauth_token_secret,
    oddělený ampersandem (&)

    Nemáte-li oauth_token_secret hodnotu, ampersand (&) musíte do šifrovacího klíče stejně „přidat“.

Pomohl Vám tento článek?

Děkujeme za odpověď