Lucrarea 6 – Integrare API

Resurse necesare

• Sistem de calcul dotat cu sistemul de operare Windows 10 sau Windows

7 în configurația monitor, mouse, tastatură;
• Mediu de dezvoltare Visual Studio 2019 sau Visual Studio 2017 instalat.

Obiective

• Studiul tehnicilor de preluare și prelucrare a datelor obținute din execuția

unui API;
• Utilizarea metodelor XML.

Un API (Application Programming Interface) reprezintă un set de protocoale și

instrumente utilizate pentru dezvoltarea programelor. Un API poate fi considerat un mijloc
de comunicație dintre două aplicații, fără a fi necesar să se cunoască modalitatea în care
aplicațiile sunt dezvoltate. Un exemplu concret este acela când două persoane vorbitoare
de limbi diferite necesită să poarte o conversație. Pentru a se putea înțelege este necesar un
translator. Translatorul, indiferent dacă este o persoană sau o aplicație, preia declarația
unuia dintre vorbitori și o adaptează limbajului celui de-al doilea vorbitor. Din această
perspectivă, obiectivul principal al unui API este de a transfera date între două servicii, fără
a cunoaște detalii de implementare.

API-urile primesc date de la un program într-un anumit format și le transmit către

cel de-al doilea program. Formatul este de obicei standardizat prin intermediul
instrumentelor XML sau JSON.

XML (eXtensible Markup Language) reprezintă un instrument care stochează datele

sub forma de noduri și le transmite către o aplicație unde datele vor fi extrase și prelucrate
pentru îndeplinirea unui obiectiv. Acest instrument a fost proiectat special pentru a putea
fi accesbil atât operatorului uman, cât și nivelului cod – mașină, astfel încât integrarea să
se poată realiza facil. Datele plasate sub formă de noduri este similară scrierii HTML,
fiecare nod fiind demarcat de tag-uri. În interiorul unui nod sunt plasate atributele. Tag-
urile nu sunt predefinite, ci sunt atribuite de către dezvoltatorul programului și declarate
ulterior ca standard în documentația API-ului.

Structura XML presupune existența unui nod rădăcină, în interiorul căruia există
nodurile părinți. Un exemplu de nod rădăcină este în exemplul de mai jos nodul numit
curent, unde nodul temperatura este nodul părinte.

<curent>
<temperatura value="11.96" min="8.55" max="13.16" meas="celsius"/>
<tara>RO</tara>
</curent>
Cele mai importante caracteristici ala unui nod XML sunt:

- Text, cum este RO în exemplul de mai sus;

- Atribute, ca de exemplu value pentru nodul temperatura.

Integrarea unui API într-un program necesită parcurgerea următoarelor etape:

- Se identifică API-ul care îndeplinește în totalitate cerințele problemei;

- Se creează un cont în cadrul platformei care oferă API-ul și se generează o cheie
care permite accesarea API-ului;
- Se citește documentația pentru a identifica adresa API-ului în format necesar
aplicației;
- Se creează aplicația care va accesa API-ul, în cadrul căreia vor fi introduse:
o Cheia de acces;
o Se accesează adresa API-ului care va returna un răspuns în format XML;
o Se parcurge răspunsul pentru extragerea datelor necesare aplicației proiectate
și implementate.
 În C# clasa responsabilă cu preluarea datelor dintr-un format XML este
XMLDocument și aparține namespace-ului System.XML. Pentru exemplificare, se va
utiliza API-ul de extragere a temperaturii pentru un anumit oraș, folosind serviciul
openweathermap.org. Pentru aceasta, se va crea un cont, iar accesând adresa
https://home.openweathermap.org/api_keys se va genera un API key.

Ulterior, se va accesa documentația https://openweathermap.org/current care

detaliază modalitatea de construire a link-ului pentru a returna în program în format XML
temperatura pentru un anumit oras, ca de exemplu Ploiesti. Din documentație, link-ul
construit va avea forma
https://api.openweathermap.org/data/2.5/weather?q=Ploiesti&units=metric&mode=xml&
appid=5cda39f79fc57d411e65c9e599790d86, unde:

- units = metric specifică faptul că unitatea de măsură este grade Celsius;

- mode = xml menționează că rezultatul trebuie să fie în format xml;
- appid=CHEIE, reprezintă cheia de acces la API.

Un exemplu de rezultat returnat este:

<current>
<city id="670474" name="Ploieşti">
<coord lon="26.0167" lat="44.95"/>
<country>RO</country>
<timezone>7200</timezone>
<sun rise="2021-11-13T05:10:47" set="2021-11-13T14:49:50"/>
</city>
<temperature value="11.96" min="8.55" max="13.16" unit="celsius"/>
<feels_like value="10.52" unit="celsius"/>
<humidity value="50" unit="%"/>
<pressure value="1022" unit="hPa"/>
<wind>
<speed value="2.65" unit="m/s" name="Light breeze"/>
<gusts value="3.09"/>
<direction value="108" code="ESE" name="East-southeast"/>
</wind>
<clouds value="100" name="overcast clouds"/>
<visibility value="10000"/>
<precipitation mode="no"/>
 <weather number="804" value="overcast clouds" icon="04d"/>
<lastupdate value="2021-11-13T12:44:53"/>
</current>

Cele mai utilizate metode C# care permit accesare și preluarea datelor din API sunt:

1. Metoda care permita accesarea adresei URL a API-ul și returnează rezultat în format
XML este Load(). Această metodă primește ca parametru o adresă, iar prototipul
este:

public virtual void Load (adresă_URL);

2. Metoda de preluare a elementelor după numele tagului este

GetElementsByTagName(). Această metodă primește ca parametru un string
reprezentând numele tag-ului și returnează o listă de noduri XML:

public virtual XmlNodeList GetElementsByTagName (string name);

3. Metoda de preluare a unui element după identificator (id) se numește

GetElementById(). Metoda primește ca parametru numele identificatorului sub
forma unui șir de caractere și returnează un element în format XML sau valoarea
null în cazul în care niciun element nu îndeplinește condiția de nume:

public virtual XmlElement? GetElementById (string elementId);

4. Proprietatea DocumentElement permite preluarea conținutului nodului rădăcină.

Dacă nu există un nod rădăcină, atunci va returna valoarea null. În caz contrar,
valoarea returnată este de tip XmlElement. Această proprietatea este esențială în
accesarea nodurilor copil.
5. Proprietatea InnerText preia în format string valoarea nodului curent, împreună cu
toate nodurile copil.
 6. Proprietățile FirstChild, LastChild permit preluarea primului, respectiv a ultimului
nod din interiorul unui nod părinte. Rezultatul returnat este de tip XmlNode.
7. NextSibling și PreviousSibling reprezintă proprietăți pentru accesarea următorului
frate în lista de noduri XML, respectiv a fratelui anterior. Rezultatul returnat este de
tip XmlNode;
8. Attributes preia lista atributelor existente într-un element. Pentru a putea aplica
metoda, trebuie referit elementul de tip XmlNode. Proprietatea se utilizează fie prin
accesarea elementului cu ajutorul unui index de tip numeric (de exemplu
.Attributes[0]), situație în care modificarea răspunsului trimis de API va strica
preluarea datelor, fie utilizând metoda GetNamedItem() care primește ca parametru
de intrare numele atributului care se dorește a se extrage. Metoda primește ca
parametru o valoarea de tip string și returnează o valoare XmlNode din care se va
extragea proprietatea Valoare pentru identificarea valorii proprietății specificate.

Problema 1: Se cere să se afișeze din exemplul de API referitor la monitorizarea meteo

orașul, temperatura curentă, temperatura resimțită, viteza și direcția din care bate vântul.

Pentru implementare se parcurg următoarele etape:

- Se declară clasa infoMeteo cu proprietățile numeOras, temperaturaCurenta,

temperaturaResimtita, vitezaVant și directieVant pentru a păstra datele solicitate de
cerința problemei;
- În interiorul metodei principale a clasei Program:
o se instanțiază obiectul xml al clasei XmlDocument;
o se apelează metoda Load() pentru apelarea API-ului;
o se declară obiectul im al clasei infoMeteo;
o pentru a prelua numele orașului se extrage cu proprietatea DocumentElement
conținutul nodului rădăcină, iar ulterior se extrage primul nod copil pentru
care se preia valoarea atributului name din lista de atribute;
 o pentru extragerea temperaturii curente se extrage din valorile returnate de
proprietatea DocumentElement nodul cu numele temperature din care se
preia valoarea atributului value din lista atributelor;
o pentru extragerea temperaturii resimtițe se procedează similuar temperaturii
curente, cu observația că numele nodului copil este feels_like;
o în cazul nodului wind, se preia nodul copil cu numele speed și ulterior se
accesează valoarea atributului value pentru a putea accesa viteza vântului;
o în mod similar se procedează și pentru preluarea direcției vântului, unde
nodul copil al nodului wind se numește direction;
o se afișează toate proprietățile obiectului creat.

Codul care implementează descrierea anterioară este:

public class infoMeteo

{
public string numeOras { get; set; }
public string temperaturaCurenta { get; set; }
public string temperaturaResimtita { get; set; }
public string vitezaVant { get; set; }
public string directieVant { get; set; }
}
class Program
{
static void Main(string[] args)
{

XmlDocument xml = new XmlDocument();

xml.Load(@"https://api.openweathermap.org/data/2.5/weather?q=Ploiesti&units=m
etric&mode=xml&appid=5cda39f79fc57d411e65c9e599790d86");

infoMeteo im = new infoMeteo();

im.numeOras =
xml.DocumentElement.FirstChild.Attributes.GetNamedItem("name").Value;
im.temperaturaCurenta =
xml.DocumentElement.SelectSingleNode("temperature").Attributes.GetNamedItem("value").Value;
im.temperaturaResimtita =
xml.DocumentElement.SelectSingleNode("feels_like").Attributes.GetNamedItem("value").Value;
 im.vitezaVant =
xml.DocumentElement.SelectSingleNode("wind").SelectSingleNode("speed").Attributes.GetNamedIte
m("value").Value;
im.directieVant =
xml.DocumentElement.SelectSingleNode("wind").SelectSingleNode("direction").Attributes.GetNamed
Item("code").Value;

Console.WriteLine("Nume oras: " + im.numeOras);

Console.WriteLine("Temperatura curent: " + im.temperaturaCurenta);
Console.WriteLine("Tempartura resimtita: " + im.temperaturaResimtita);
Console.WriteLine("Viteza vant: " + im.vitezaVant);
Console.WriteLine("Directie vant: " + im.directieVant);
}
}

Figura 6.1 prezintă rezultatul execuției programului de extragere a numele orașului,

temperaturii curente, temperaturii resimțite, vitezei și direcției vântului.

Fig. 5.1. Rezultatul execuției programului prezentat.

Problema 2: Să se extragă și să se afișeze ziua și cursul valutar pentru monedele EUR și

USD oferite de Banca Națională a României pentru ultimele 10 zile. Cursul pieței valutare
este oferit în format XML, prin accesarea adresei:

https://www.bnr.ro/nbrfxrates10days.xml

Pentru implementare se parcurg următoarele etape:

- se instanțiază obiectul xd al clasei XmlDocument;

- se apelează adresa API-ului pentru extragerea datelor XML;
 - se extrage conținutul rădăcinii, apoi ultimul nod care corespunde tag-ului body și
apoi ultimul nod corespunzător tag-ului Cube;
- deoarece se va afișa cursul valutar pentru ultimele 10 zile, se realizează o parcurgere
în 10 pași pentru care:
o din ultimul nod se extrage valoarea atributului date pentru afișarea zilei care
corespunde cursului valutar;
o se extrag toate nodurile copil în lista de noduri valutaList;
▪ se parcurg toate elementele din valutaList:
• dacă elementul curent are valoarea atributului currency egală
cu EUR, atunci se afișează valoarea din interiorul tag-ului;
• dacă elementul curent are valoarea atributului currency egală
cu USD, atunci se afișează valoarea din interiorul tag-ului;
o se trece la nodul frate precedent.

Codul care implementează descrierea anterioară este:

XmlDocument xd = new XmlDocument();

xd.Load(@"https://www.bnr.ro/nbrfxrates10days.xml");

XmlNode ultimulNod = xd.DocumentElement.LastChild.LastChild;

for (int i = 0; i < 10; i++)
{
string data = ultimulNod.Attributes.GetNamedItem("date").Value;

Console.WriteLine("Data: " + data);

XmlNodeList valutaList = ultimulNod.ChildNodes;

foreach (XmlNode c in valutaList)
{
if (c.Attributes.GetNamedItem("currency").Value == "EUR")
Console.WriteLine("EUR: " + c.InnerText);

if (c.Attributes.GetNamedItem("currency").Value == "USD")
Console.WriteLine("USD: " + c.InnerText);
}
ultimulNod = ultimulNod.PreviousSibling;
}

În figura 6.2 este prezentată o secvență din execuția programului:

Fig. 6.2. Secvență din execuția programului în care sunt afișate: data – valoarea EUR –
valoarea USD pentru ziua respectivă.