Pre potreby mobilných a desktopových aplikácií bolo do Netquest API implementované OAuth rozšírenie pomenované Xauth (riešenie známe z API Twitteru). Implementácia OAuth protokolu v rôznych jazykoch sa nachádza na http://oauth.net/code/.

Získanie kľúča access_token

Pre prihlásenie do API použitím Xauth je potrebné mať kľúče consumer_key a consumer_secret.
Požiadavka musí byť zaslaná na adresu

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

odovzdaním nasledujúcich dát použitím metódy POST:

$params = array(
   //uživatelske meno, pre ktoré má byť token získaný
   'x_auth_username' => '[email protected]', 
   //enkódované heslo pre užívateľa, pre ktorého má byť token získaný
   'x_auth_md5_password' => md5('vaseheslo')
   //tento parametr musí mať rovnakú hodnotu
   'x_auth_mode' => 'client_auth'
);

Hlavička Authorization musí mať následujúcu 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 úspešnom autorizovaní budú ako odpoveď vrátené oauth_token a oauth_token_secret.
V tomto momente by mala aplikácia odstrániť dáta užívateľa
(x_auth_username a x_auth_md5_password) a použiť štandardné OAuth procedúry na overovanie na serveri.

Ukážka

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

$params = array(
	'x_auth_username' => '[email protected]',
	'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"
 * }
 */

Aplikácia klienta by mala mať token a token_secret, ktoré spoločne s consumer_key a consumer_secret umožňujú správne overenie.

Ukážka – Posielanie požiadavky menom používateľa

Cieľ: Získanie zoznamu respondentov z konkrétneho dotazníka

Pre tento účel budeme používať oauth_token a oauth_token_secret

Z dotazníka ID=1234 získame zoznam respondentov, ktorí vyplnili dotazník 1. júla, 2011 (2011-07-01).
Dodatočne, máme záujem len o 10 respondentov.

Pre získanie zoznamu respondentov s vyššie uvedenými parametrami je nutné použiť operáciu vyhľadávania respondentov, dostupnú na

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

Požiadavka bude odoslaná použitím metódy POST za účelom odovzdania parametrov hľadania. Dodatočné parametre budú potrebné aj pre správne vykonanie OAuth/Xauth požiadavky. Všetky potrebné parametre sú uvedené nižšie.

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ásledne vytvoríme signature base string podľa rovnakých pravidiel, ako boli použité pre získanie tokena.

POST&https%3A%2F%2Fwww.netquest.sk%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

Ďalší krok je vytvorenie šifrovacieho kľúča pre generovanie podpisu pomocou oauth_consumer_secret a oauth_token_secret

07d740ac3613874f9528c3eab0279b98&ab8b78bbebb38b76f444c8a2ddf162ff

Použitím šifrovacieho kľúča 'podpíšeme' signature base string. Vo výsledku dostaneme:

JWrgkCsKm3OTpEQR5RI7kmtlpco%3D

Potom vytvoríme HTTP autorizačnú hlavičku Authorization. Samozrejme, všetky tieto hodnoty musia byť enkódované (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 prvkom je prevedenie POST požiadavky na Netquest API (koncový bod). Potom už iba držať palce, aby všetko pracovalo správne :-).
Po úspešnom vykonaní požiadavky by sme mali obdržať nasledujúcu odpoveď:

{
	"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":"[email protected]",
		"label1":"Petr",
		"label2":"Novak",
		"label3":"774 700 800",
		"label4":"",
		"label5":"",
		"answer_postponed":null
	},{
		...
	}]
}

Podpisovanie HTTP požiadavky

Všetky OAuth 1.0 požiadavky používajú rovnaký základný algoritmus pre vytváranie reťazca podpisu (signature base string) a vytváranie podpisu.

Vytvorenie signature base string je jedna z najnáročnejších častí OAuth štandardu.
Text tvorí následujúce časti:

1. použitý názov metódy (GET nebo POST)
2. link-character ampersand ("&")
3. enkódovaná URL s adresou operácie, napr. https://www.netquest.sk/api/surveys
4. link-character ampersand ("&")
5. parametre zaslané prostredníctvom POST požiadavky a OAuth parametre nevyhnutné pre overenie i.

Vyššie uvedené parametre (POST i OAuth) musia byť radené v lexikografickom usporiadaní.

Obaja parametre a hodnoty musia byť enkódované (urlencode).
Ak sa nachádza v hodnote parametra medzera, mala by byť odoslaná ako %20

Namiesto znaku pre rovná sa "=" (relácia kľúč/hodnota) by mala byť použitá enkódovaná podoba
– "%3D".
Hodnota každého parametra (kľúč/hodnota) by mala byť spojená enkódovaným & (ampersand) – "%26".

Vyššie uvedený algoritmus môže byť predložený ako pseudo-kód zobrazený nižšie:

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

Bez ohľadu na to, aký typ žiadosti vykonávate, pravidlá generovania signature base string sú vždy rovnaké.

Netquest API vyžaduje OAuth/Xauth podpísanie požiadaviek s HMAC-SHA1 algoritmom.

Slovník

• oauth_nonce – Jedinečný identifikátor každej HTTP požiadavky generovanej aplikáciou klienta.
  Netquest API umožňuje použiť jednu hodnotu oauth_nonce pre jednu požiadavku. Cieľom je eliminovať opakujúce sa volanie rovnakej požiadavky.
• oauth_timestamp – Celé číslo predstavujúce počet sekúnd, ktoré uplynuli od 1. januára 1970.
  Hodnota klientovho TIMESTAMP sa nemôže líšiť od hodnoty TIMESTAMP servera o viac ako 600 sekúnd (10 minút)
  Ak je rozdiel väčší, HTTP požiadavka bude ignorovaná.
• signature base string – „Zostavený „text, podpísaný pomocou šifrovacieho kľúča pre generovanie podpisu HTTP požiadavky – oauth_signature
  Príklad vytvorenia podpisu je popísaný v časti Podpisovanie HTTP požiadavky
• encryption key – Text (reťazce) použitý ako „tajný kľúč” pre podpisovanie HTTP požiadaviek.
  Podľa OAuth 1.0 štandardu je šifrovací kľúč vypočítaný podľa nasledujúceho algoritmu:

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

  Niektoré z požiadavky OAuth vyžadujú použitie oauth_token_secret, zatiaľ čo ostatné nie.

  Šifrovací kľúč je vždy zložený z hodnôt consumer_secret a oauth_token_secret,
  oddelený ampersandom (&)

  Ak nemáte oauth_token_secret hodnotu, ampersand (&) musíte do šifrovacieho kľúča aj tak „pridať”.