Dacă lucrați chiar și de la distanță în apropierea industriei de dezvoltare web, puteți fi 100% sigur că veți auzi acele trei litere infame: API.

Conversațiile despre ei sunt împrăștiate între noob și experți:

„De ce ar trebui să fac un apel API? Are un număr?

„Un simplu apel la acest API terță parte vă va ajuta să realizați acest lucru.”

„Vom crea un API RESTful pentru tine; asigurați-vă că noul dumneavoastră sistem funcționează bine cu alte servicii.”

Deși API-urile pot părea înfricoșătoare la început, ele îți pot schimba literalmente viața de dezvoltator.

Pentru ce? Ei bine, învățarea cum să utilizați corect API-urile vă poate simplifica, accelera și consolida fluxul de lucru de dezvoltare. Crearea sau integrarea API-urilor aduce beneficii semnificative atât clienților dvs., cât și dumneavoastră.

În calitate de dezvoltatori, auziți adesea sfatul „nu reinventați roata”:

glumă:
sfat înțelept: nu reinventați roata
programator: ok
nu mai scrie niciodată cod personalizat

Glume deoparte, API-urile joacă un rol important în a se asigura că nu reinventezi roata. La Snipcart, credem cu tărie că înțelegerea fundamentelor API este o abilitate cheie pentru dezvoltatorii web moderni. În această postare te vom ajuta să faci exact asta. Vom lua în considerare:

Beneficiile utilizării unui API Ce este de fapt un API Ce tipuri de API există Exemple practice de utilizare a unui API

Ei bine, nu este timpul să ne scufundăm?

Beneficiile API-urilor: de ce să le folosiți?

Unul dintre primii și cei mai importanți pași din cariera mea de programator a fost înțelegerea corectă a API-ului.

Încă le folosesc în fiecare zi.

Înainte de a intra în esență, permiteți-mi să vă conving că înțelegerea API-ului merită timpul dvs.

Deoarece învățarea utilizării API-urilor vă îmbunătățește foarte mult eficiența dezvoltării.

În primul rând, vă permite să utilizați unul existent logică sau părți, pe care nu trebuie să-l scrii singur. Unele lucruri pe care s-ar putea să nu le poți scrie singur! Prin urmare, pentru a economisi timp prețios, este foarte important, ca dezvoltator, să aveți o idee despre cum arată API-ul.

În al doilea rând, multe dintre problemele de dezvoltare pe care le vei întâlni au fost deja rezolvate de altcineva înaintea ta. Indiferent de forma pe care o iau aceste soluții existente (FaaS, biblioteci, servicii web, SDK-uri, API-uri de conținut etc.), cel mai probabil veți avea nevoie de un API pentru a interacționa cu ele.

Deci, ce este un API?

Ei bine, definiția oficială, înfricoșătoare este:

În programarea computerelor, o interfață de programare a aplicațiilor (API) este un set de definiții de rutină, protocoale și instrumente pentru crearea de software de aplicație. În termeni generali, este un set de metode de comunicare bine definite între diferite componente software. Un API bun facilitează dezvoltarea unui program de calculator, oferind toate elementele de bază pe care programatorul le asambla apoi.

E greu, nu? Să luăm proza ​​academică mai jos. Iată o definiție mai prietenoasă a unui API de acasă:

Mai simplu spus, un API declară o interfață cu care logica sa interacționează fără a fi nevoie să știe ce se întâmplă înăuntru. Această definiție poate fi aplicată oricărei limbi, protocol sau mediu în care vă aflați, atâta timp cât se află nivelul programului(mai multe despre asta mai jos).

Pentru a arunca puțină lumină asupra API-urilor, să enumerăm ce NU sunt acestea:

Un API nu este neapărat un serviciu extern. De exemplu, puteți include biblioteci direct în soluția dvs. SAU le puteți utiliza printr-un API.

Un API este mai mult decât o interfață. Aceasta este atât specificația/formatul, cât și implementarea.

API-ul nu este o interfață grafică cu utilizatorul (GUI). Nu face interacțiune la nivel grafic; funcționează exclusiv la nivel de software, fie printr-un limbaj de programare, fie printr-un protocol de comunicații.

De asemenea, API-ul nu este un web-hook. Dacă întâmpinați probleme în a înțelege diferența dintre cele două, iată o introducere în Web Hooks.

Diverse tipuri de API

Toate API-urile nu sunt create egale.

Deși în mare parte au același scop, unii îl ating mai bine decât alții. Deoarece aceasta ar trebui să fie o introducere simplă, nu voi intra în ceea ce face API-ul mai bun decât altele. Cu toate acestea, rețineți că oamenii au abordări diferite pentru a crea API-uri. Dacă sunteți interesat de acest subiect, Google „API Design Patterns” și „API Paradigms”. Sau începeți pur și simplu cu acest articol frumos de nivel de intrare https://translate.googleusercontent.com/translate_c?depth=1&rurl=translate.google.ru&sl=auto&sp=nmt4&tl=ru&u=https://blog.cloudobjects.io/api-design / 2017/04/10/api-design-paradigms/&xid=17259,15700019,15700186,15700190,15700248,15700253&usg=ALkJrhg_fNGbUZsc4_Ezoo :)

Scopul unui API este de a vă ușura viața de dezvoltator. Cum o fac? Prin combinarea unei colecții de caracteristici/funcții și expunerea acelor caracteristici prin punctele finale (de obicei, modele URL utilizate pentru a interacționa cu API-ul). Aceste puncte finale sunt singura modalitate de a interacționa cu orice API. Fiecare punct final va avea un format specific pentru cererile și răspunsurile sale - de obicei veți găsi acest format în documentația API.

Punctele finale pot fi funcții simple sau alcătuite din multe funcții care apelează alte API-uri și așa mai departe. Singurul punct important aici este că logica de bază a acestor funcții este complet abstractizată. Nu aveți nevoie de cunoștințe despre ceea ce se întâmplă în interiorul lor pentru a le folosi. Atâta timp cât folosești formatul corect, le vei putea folosi, ceea ce este un mod elegant de a spune, folosind părți din ele din aplicația ta.

În concluzie, un API este ca orice interfață: un întrerupător de lumină va aprinde o lumină, indiferent dacă știi cum funcționează curenții electrici (sau am învățat și eu când eram tânăr că trebuie să plătești o factură pentru a o face să funcționeze pentru electricitate, dar asta e alta poveste.)

Cum se utilizează API-ul: exemple practice

Citirea și înțelegerea documentației API

Din documente puteți vedea că fiecare funcție de obiect descrie care ar trebui să fie formatul de intrare (număr, matrice de numere etc.) și descrie formatul de ieșire. Rețineți, totuși, că nu este menționat nimic în ceea ce privește logica pentru a rula aceste funcții. De exemplu, dacă rulați consola pentru dezvoltatori și Math.sqrt (fără a executa funcția), veți obține ceva de genul ƒ sqrt() ( ) . Acesta este spiritul API-urilor: indiferent dacă apelați unul dintre API-urile sistemului dvs. de operare sau un API web, aceste principii rămân aceleași.

Exemple de utilizare de bază a API-ului

Există o mulțime de lucruri de făcut cu furnizorii populari de API. De exemplu, API-ul Google Maps este adesea folosit pentru a îmbunătăți experiența utilizatorului cu date bazate pe afișaje în timp real și pe semnale de trafic. API-ul Twitter, un alt mare, poate fi folosit pentru a filtra și afișa tweet-uri vizate în timp real.

Acum, dacă ați urmărit blogul nostru, bănuiesc că sunteți mai interesat de API-urile web decât de orice altceva. Deci, haideți să ne aprofundăm în cazuri de utilizare specifice. Vă rugăm să rețineți că vom folosi Postman în exemplele noastre. Desigur, acest client Rest este asociat cu un mediu web, dar astfel de instrumente există de obicei și în alte medii. Merită să aruncați o privire asupra instrumentelor oferite pentru un anumit mediu înainte de a începe să vă jucați cu el; vă poate economisi mult timp.

Dacă doriți să ne urmăriți, trebuie să descărcați clientul Postman. https://www.getpostman.com/

Utilizarea API-ului public pentru a prelua date

Primul nostru exemplu va fi destul de simplu, dar totuși mai interesant decât cel matematic.

Vom folosi API-ul Dog! Nu numai că este un API distractiv, dar și nu necesită nicio autentificare. În plus, este un API REST HTTP, ceea ce înseamnă că este un API web. Deoarece este asociat cu acest mediu, ne cere să respectăm unele caracteristici specifice ale protocolului: în acest caz verbe HTTP (GET, PUT, POST, DELETE etc.). În exemplul nostru, îl vom păstra simplu și vom folosi doar verbul GET. În orice caz, API-ul nu vă permite să susțineți nimic altceva. Majoritatea API-urilor publice vă permit doar să consumați date, nu să le publicați, cum ar fi verbul GET.

Să lansăm Postman și să vedem cum arată interfața sa de utilizator.

Interfața mea de utilizare folosește o temă întunecată, așa că poate arăta puțin diferit de a ta.

Pot fi multe informații de digerat la început, așa că să începem cu VERB și URL.

Verbul implicit ar trebui să fie GET, astfel încât să îl puteți lăsa așa și să introduceți următorul URL: https://dog.ceo/api/breeds/list/all

Faceți clic pe „Trimite” și gata! Ar trebui să primiți un răspuns cu datele relevante. Voila! Tocmai ați efectuat primul apel API. Acum, pentru acest exemplu, nu vom folosi niciuna dintre datele primite. Dar aveți o idee: puteți arăta diferite rase de câini utilizatorului dvs. și puteți afișa o imagine a acelei rase dacă dă clic pe ea.

Vă puteți juca cu diferitele rute din documentația lor pentru a vă familiariza cu mediul.

Fapt interesant: acest mic proiect este, de asemenea, open source, așa că îl puteți verifica aici https://github.com/ElliottLandsborough/dog-ceo-api.

Gestionarea autentificării utilizând API-ul privat

Aici vom folosi codul doar pentru a interacționa cu API-ul Snipcart https://docs.snipcart.com/api-reference/introduction. Poți închide Poștașul, dar ține-l la îndemână; Este bine să folosiți un astfel de instrument atunci când rulați cu un API.

Scopul va fi crearea unui instrument CLI simplu pentru a genera reduceri de utilizare unică pentru clienți. Aceste reduceri vor fi generate printr-un API și se vor întâmpla în întregime pe computerul dvs.

Creați un folder nou pentru acest proiect, utilizați npm init în folder și încărcați editorul de text. Acum creați un fișier index.js, apoi deschideți fișierul package.json. În el, adăugați următoarele linii la obiectul de nivel superior:

„bin”: ( „reduceri”: „./index.js”)

Vom avea nevoie, de asemenea, de pachetul comandant pentru a analiza intrarea de la client. Deci, rulați npm install -save commander în folderul curent. De asemenea, vom folosi o mică bibliotecă pentru a crea identificatori; Îl puteți instala folosind npm install -save shortid . În timp ce suntem la asta, să rulăm și npm install -save request lib, astfel încât să putem face apelurile HTTP mai ușoare. Reveniți la fișierul index.js și inserați acest cod:

#!/usr/bin/env node var program = require(‘comandant’); var shortid = require(‘shortid’); var cerere = require('cerere'); funcția CreateDiscount())( var discount = ( nume: „20% OFF”, declanșare: „Cod”, tip: „Rate”, rate: 20, maxNumberOfUsages: 1, cod: shortid.generate() ) request(( url : „http://app.snipcart.com/api/discounts" , auth: ( 'utilizator': 'YOUR_API_KEY' ), metoda: „POST”, json: true, body: discount ), funcție (eroare, răspuns, body )( console.log(body.code); )); ) program .arguments(' ') .action(function(number) ( for(var i = parseFloat(number); i > 0; i-)( CreateDiscount ( ); ) )).parse(process.argv);

Să ne concentrăm doar pe funcția de solicitare aici. Aici efectuăm un apel API extern către Snipcart. Puteți vedea că trecem metoda: „POST” metodei. Acest lucru se datorează faptului că dorim să publicăm date în API-ul Snipcart. Specificând această metodă, API-ul va reda acțiunea corect, astfel încât să poată citi corpul cererii, care conține datele de reducere.

O caracteristică API interesantă pe care nu am folosit-o încă este autentificarea. Toate celelalte exemple ale noastre au fost pe API-uri publice: nu necesită autentificare. Dar, în scenariile din lumea reală, majoritatea API-urilor pe care le utilizați vor necesita probabil un fel de autentificare, cum ar fi API-ul Twitter sau API-ul Google Maps. Acesta este un „model” standard în lumea API. Clienții noștri nu ar fi la fel de fericiți dacă l-am lăsa pe altcineva să creeze reduceri în magazinul lor. ;)

Conceptele de autentificare pot deveni destul de greoaie; Puteți citi această postare grozavă https://translate.googleusercontent.com/translate_c?depth=1&rurl=translate.google.ru&sl=auto&sp=nmt4&tl=ru&u=http://blog.restcase.com/restful-api-authentication- elemente de bază /&xid=17259,15700019,15700186,15700190,15700248,15700253&usg=ALkJrhjwWO5yc6nayLpXCQkh_X95B0OZMw pentru a stăpâni mai bine subiectul.

În scopul nostru, transmitem cheia API https://translate.googleusercontent.com/translate_c?depth=1&rurl=translate.google.ru&sl=auto&sp=nmt4&tl=ru&u=https://en.wikipedia.org/wiki/Application_programming_interface_key&xid =17259, 15700019,15700186,15700190,15700248,15700253&usg=ALkJrhhpSWyk-nV9379VcrY3TMcKiAdXlQ direct în cerere și urează serverul! Apoi poate face o solicitare specifică numai contului nostru.

Dacă doriți să testați mica noastră aplicație, puteți rula npm install -g în directorul proiectului și pur și simplu rulați reduceri x pentru a crea reduceri x de ori. Puteți accesa tabloul de bord Snipcart (conturi pentru totdeauna gratuite în modul de testare) și vă asigurați că reducerile au fost create corect. Vă puteți imagina cât de puternic poate fi acest lucru: dacă ar trebui să creați 200 dintre aceste reduceri, ar dura prea mult timp să o faceți prin interfața noastră cu utilizatorul. Cu toate acestea, odată ce vă familiarizați cu modul în care funcționează API-ul, se poate face în câteva minute. Codul este și reutilizabil, așa că dacă trebuie să faci același lucru într-o lună, ei bine, ești gata!

Dacă aveți cazuri de utilizare specifice pentru API despre care doriți să vorbiți, vă rugăm să le scrieți în comentarii. Vom analiza să le adăugăm în foaia noastră de parcurs de conținut! :)

Gânduri finale

Sper din tot sufletul că acest tutorial v-a ajutat să înțelegeți mai bine ce sunt API-urile și cum le puteți utiliza în fluxul de lucru de dezvoltare.

Câteva concluzii:

• API-urile vă vor accelera viteza și vă vor extinde capacitățile de dezvoltare. Utilizati-le!
• API-urile nu sunt neapărat legate de ecosistemul web; Le vei vedea peste tot.
• Verificați întotdeauna cu atenție documentația API-ului pe care doriți să îl utilizați.
• Căutați întotdeauna instrumentele existente (API-uri sau altele) în ecosistemul dvs. înainte de a începe să codificați.

Acum, ultimul nostru exemplu nu este gata de „producție”, dar vă oferă o idee bună despre cum ar putea arăta lucrurile în viața reală. Există multe lucruri pe care le-am putea îmbunătăți, cum ar fi să permitem utilizatorului să selecteze tipul de reducere etc. De asemenea, am putea folosi codurile generate pentru a le trimite prin e-mail direct în aceeași funcție, mai degrabă decât să le înregistrăm. Dacă am avea nevoi mai mari pentru instrumentele noastre de reducere, am putea scrie API-ul singuri. De acolo am putea chiar să creăm o interfață de utilizare care interacționează cu API-ul nostru, dacă dorim. Oricum, sper că ai prins ideea acum! :)

Deci, care este următorul pas? Ca aproape tot ce se află în dezvoltare, trebuie să codificați, să codificați, să codificați și să mai codificați! Acest lucru vă va introduce în gestionarea și integrarea API. După un timp vei deveni mai eficient cu ele.

Și de aici începe adevărata distracție.

Lucrul cu API-uri poate fi atât satisfăcător, cât și frustrant. Pe de o parte, interacționând cu alte aplicații, puteți crește considerabil acoperirea publicului și efectul „wow” al aplicației dumneavoastră. Pe de altă parte, aceasta implică citirea de tone de documentație, studierea strategiilor de autentificare și analizarea mesajelor de eroare neinformative (sau chiar lipsă).

În primul rând, dacă încă nu înțelegi pe deplin ce este un API (Application Programming Interface), citește explicația Skillcrush și apoi prima parte a acestui articol pentru a prinde din urmă.

„API” este un concept incredibil de larg - de fiecare dată când aplicația ta „vorbește” cu o altă aplicație, o face printr-un fel de API. Componentele din propria aplicație, cum ar fi diferite părți ale Rails, vorbesc între ele prin intermediul API-urilor. Sunt subaplicații mai mult sau mai puțin independente care oferă datele de care fiecare dintre ele are nevoie pentru a-și îndeplini propriile sarcini specifice. În lumea aplicațiilor, totul este un API!

Când construiți aplicații cu funcționalitate front-end mai dinamică (atât aplicații Javascript cu o singură pagină, cât și aplicații simple cu apeluri AJAX individuale), acestea vor comunica cu backend-ul Rails prin propriul dvs. API, care este de fapt doar o linie suplimentară sau două de cod. , spunându-le controlorilor cum să difuzeze JSON sau XML în loc de HTML.

În acest tutorial veți învăța cum să vă creați propriul API. În lecțiile ulterioare vom aborda modul de a interacționa cu API-urile altor aplicații. Lecțiile ar trebui să fie o bună rampă pentru a învăța despre acest subiect, dar este puțin probabil să acopere pe deplin toate cazurile. O mare parte a lucrului cu API-urile este să știi cum să le citești documentația și să-ți dai seama ce vor de la tine.

Puncte de luat în considerare

Examinați întrebările și vedeți dacă știți răspunsurile. Testează-te din nou după finalizarea sarcinii.

• Cum înțelege Rails ce tip de fișier așteptați ca răspuns atunci când trimiteți o solicitare HTTP.
• Care este scopul metodei #respond_to?
• Cum returnați un obiect User în timp ce specificați atributele pe care nu doriți să le includă în acel obiect (adică nu puteți returna pur și simplu User.first)?
• Numiți cei 2 pași din culisele metodei #to_json.
• Cum îi spui unei acțiuni controlerului să redea doar un mesaj de eroare?
• Cum să-ți creezi propriul mesaj de eroare?
• De ce nu puteți utiliza metode de autentificare a controlerului bazate pe sesiune dacă doriți să permiteți conexiuni programatice la API-ul dvs.?
• Ce este „Arhitectura Orientată pe Servicii”?

Bazele API

Aplicația dvs. Rails este de fapt deja un API, deși s-ar putea să nu o considerați un API. Browserul web lansat de utilizatorii dvs. este, de asemenea, un program, astfel încât de fapt face o solicitare API către aplicația dvs. Rails atunci când utilizatorul deschide o pagină nouă. Avem tendința de a gândi în acest fel, deoarece redarea șabloanelor HTML este o sarcină atât de comună, încât pur și simplu introducem această funcționalitate în programele noastre de server ca tip de răspuns standard și considerăm că orice altceva este ceva neobișnuit.

Cu toate acestea, de multe ori doriți să faceți o solicitare care nu vă cere să treceți prin toate durerile de cap ale utilizării unui browser. Poate că nu vă pasă de structura paginii (HTML), dar în schimb doriți date curate. Să presupunem că doriți să obțineți o listă cu toți utilizatorii. Puteți solicita ceva de genul http://yourapplication.com/users , care va declanșa cu siguranță acțiunea #index și va afișa o listă cu toți utilizatorii aplicației.

Dar de ce să vă deranjați cu toate aceste informații suplimentare dacă tot ce doriți este o listă de utilizatori? Cea mai simplă opțiune ar fi să trimiteți o solicitare la aceeași adresă URL și să așteptați în schimb un răspuns JSON sau XML. Dacă vă configurați corect controlerul Rails, veți primi înapoi un simplu obiect matrice JSON care conține toți utilizatorii. Minunat!

Același principiu se aplică atunci când comunicați cu un API extern. Să presupunem că doriți să obțineți tweet-urile recente ale unui utilizator de pe Twitter. Tot ce trebuie să faceți este să spuneți aplicației dvs. Rails cum să interacționeze cu API-ul Twitter (adică să vă autentificați), să trimiteți cererea și să procesați setul de „tweeturi” care vor fi returnate.

Crearea unui API

Poate doriți să faceți din aplicația dvs. Rails un API backend pur pentru paginile web frontend sau poate doriți doar să învățați cum să trimiteți JSON atunci când frontend-ul solicită acest lucru. Această secțiune nu va acoperi cum să creați API-uri RESTful cu drepturi depline cu funcții de autentificare. Aceasta este o introducere simplă în tratarea aplicației dvs. ca API.

Bazele

Dacă doriți ca aplicația dvs. Rails să returneze JSON în loc de HTML, va trebui să spuneți controlerului să facă acest lucru. Lucrul grozav este că aceeași acțiune a controlerului poate returna tipuri diferite, în funcție de dacă utilizatorul face o solicitare regulată din browser sau accesează API-ul prin linia de comandă. Aceasta determină ce tip de solicitare a fost făcută pe baza extensiei fișierului solicitat, cum ar fi example.xml sau example.json.

Puteți verifica ce crede Rails despre tipul de fișier pe care îl așteptați verificând jurnalul serverului:

A început GET „/posts/new” pentru 127.0.0.1 la 2013-12-02 15:21:08 -0800 Procesarea de către PostsController#new ca HTML

Prima linie vă spune ce URL a fost solicitată, iar a doua vă spune unde a fost trimisă și cum o procesează Rails. Dacă ar fi să utilizați extensia .json, ar arăta astfel:

A început GET „/posts.json” pentru 127.0.0.1 la 2013-12-04 12:02:01 -0800 Procesarea de către PostsController#index ca JSON

Dacă rulați o aplicație de testare, încercați să solicitați adrese URL diferite. Dacă controlerul dvs. nu le poate gestiona, este posibil să primiți o eroare, dar ar trebui să puteți vedea în continuare ce înțelege Rails că sunt cererile dvs.

Redare JSON sau XML

Odată ce decideți că doriți să răspundeți la solicitări folosind JSON sau XML, va trebui să spuneți controlerului dvs. să redeze JSON sau XML în loc de HTML. O modalitate de a face acest lucru este să utilizați metoda #respond_to:

Clasa UsersController< ApplicationController def index @users = User.all respond_to do |format| format.html # index.html.erb format.xml { render xml: @users } format.json { render json: @users } end end end

În acest caz, #respond_to transmite blocului un obiect format, căruia îi puteți atașa un apel de randare corespunzător. Dacă nu faceți nimic, codul html va fi redat folosind șablonul standard Rails (în acest exemplu app/views/index.html.erb).

Funcția #render este suficient de inteligentă pentru a înțelege cum să redați o gamă largă de formate. Când îi transmiteți cheia:json , va apela #to_json pe valoarea, în acest exemplu @users . Aceasta va converti obiectele dvs. Ruby în șiruri JSON care vor fi transmise aplicației solicitante.

În acest fel, obțineți API-ul dvs. Desigur, crearea unui API poate fi puțin mai complexă dacă doriți să faceți niște lucruri fanteziste, dar totul se lipește de elementele de bază.

Specificarea atributelor returnate

Să presupunem că doriți să vă asigurați că nu returnați adresa de e-mail a utilizatorului împreună cu obiectul Utilizator. În acest caz, veți dori să modificați atributele care vor fi returnate, modificând ceea ce face metoda #to_json.

Anterior, ați fi înlocuit pur și simplu metoda #to_json cu versiunea dvs., dar acum nu va fi nevoie - de fapt, veți înlocui metoda #as_json. Metoda #as_json este folosită în metoda #to_json, deci modificarea acesteia schimbă implicit rezultatul #to_json , dar într-un mod destul de specific.

#to_json face 2 lucruri: rulează #as_json și primește un hash al atributelor care vor fi redate în JSON. Apoi se redă în JSON folosind ActiveSupport::json.encode . Deci, modificând #as_json, sunteți mai precis cu privire la partea din metoda #to_json pe care doriți să o modificați.

În cazul nostru, facem acest lucru modificând #as_json în modelul nostru pentru a returna numai atributele de care avem nevoie:

# app/models/user.rb clasa Utilizator< ActiveRecord::Base # Вариант 1: Полное переопределение метода #as_json def as_json(options={}) { :name =>self.name ) # NU includeți câmpul de e-mail end # Opțiunea 2: Folosiți metoda standard #as_json def as_json(options=()) super(only: [:name]) end end

Apoi, controlerul nostru va trebui doar să redea JSON ca de obicei (în exemplul de mai jos, JSON va fi întotdeauna returnat, indiferent dacă a fost trimisă sau nu o solicitare HTML):

# app/controllers/users_controller.rb clasa UsersController< ApplicationController def index render json: User.all end end

Rețineți că nu trebuie să apelați singur #to_json când utilizați #render - va face acest lucru pentru dvs.

Uneori, Heroku poate necesita pași suplimentari pentru a afișa corect paginile de eroare. Aruncă o privire. Poate fi necesar să eliminați mai întâi paginile statice din aplicația/directorul public.

Asigurarea securității din exterior

Să presupunem că doriți să permiteți accesul la API numai dacă utilizatorul este conectat. Autentificarea dvs. existentă în controler face deja această treabă - asigurați-vă doar că aveți setul corect #before_action (de exemplu, before_action:require_login). Este posibil să aveți nevoie de funcționalitate în care atât utilizatorii conectați, cât și cei neconectați să poată vizualiza pagina, dar fiecare ar trebui să vadă date diferite. Nu doriți ca utilizatorii neautentificați să poată efectua apeluri API pentru a obține date sensibile. De asemenea, nu doriți să permiteți utilizatorilor neautorizați să viziteze anumite pagini HTML.

Dacă doriți să procesați cereri de la o aplicație care nu este un browser (de exemplu, din linia de comandă), nu vă puteți baza pe „cookie-urile” browserului pentru autentificare. Acesta este motivul pentru care majoritatea API-urilor folosesc token-uri native ca parte a procesului de autentificare. Vom vorbi mai mult despre jetoane în următoarea lecție.

Pasii urmatori

Acum aveți abilitățile de a utiliza aplicația Rails pentru a reda nu numai HTML, ci și orice alt format. Dacă doriți să mergeți mai departe și să permiteți altor dezvoltatori să construiască lucruri folosind platforma dvs. (de exemplu, pentru a putea face solicitări programatice în loc să se autentifice ca utilizator), va trebui să vă faceți sistemul API mult mai robust. Nu vom acoperi totul aici, dar verificați următoarele:

• Articolul Building Awesome Rails API-uri descrie multe dintre cele mai bune abordări pentru trecerea de la o aplicație de jucărie la standardele API industriale.

Arhitectura orientată spre servicii

Este timpul să introducem o abordare arhitecturală numită Arhitectură Orientată pe Servicii (SOA). Ideea de bază este că aplicația dvs. va consta din multe servicii, precum un sistem de plată, înregistrarea utilizatorilor, modul de recomandare etc. În loc să construiți totul într-o singură aplicație principală, împărțiți subsistemele în bucăți complet independente care comunică între ele folosind API-uri interne.

Acest lucru este bun din multe motive. Deoarece fiecărei părți a aplicației dumneavoastră nu îi pasă de modul în care funcționează celelalte părți și știe doar cum să solicite date prin intermediul API-ului lor, puteți face modificări semnificative codului de serviciu, iar restul aplicației va funcționa ca înainte. Puteți înlocui complet un serviciu cu altul și, atâta timp cât comunică folosind aceleași metode API, va funcționa foarte bine. Puteți utiliza API-uri externe ca parte a aplicației dvs. (de exemplu, sisteme de plată) în loc să le scrieți pe ale dvs. Puteți crea o aplicație PHP care comunică cu o aplicație Python care comunică cu o aplicație Rails și totul va funcționa deoarece comunică între ele folosind un API.

În general, este o idee bună să încercați să faceți fiecare parte a aplicației dvs. cât mai independentă posibil. Conceptul de SOA te obligă să te gândești în ceea ce privește metodele pe care vrei să le expui altor părți ale aplicației tale, ceea ce îți va îmbunătăți codul. În plus, presupunând că fiecare componentă majoră a aplicației dumneavoastră este independentă, veți putea, de asemenea, să izolați problemele mult mai ușor și să gestionați erorile într-un mod mai semnificativ.

Utilizarea unei arhitecturi orientate spre servicii pentru o întreagă aplicație este ca și cum a despărți un script Ruby uriaș și complex în clase și metode ordonate, doar la scară mai mare.

Unul dintre cele mai cunoscute cazuri de tranziție la arhitectura orientată spre servicii este Amazon.com. Într-o zi din 2002, Jeff Bezos a declarat fără îndoială că toate grupurile de lucru trebuie să treacă la SOA sau să fie concediate. Notoriu postare pe blog Angajatul Google, destinat în scopuri interne, dar făcut public din greșeală, a vorbit despre puterea Amazon folosind SOA. Este o lectură grozavă, așa că asigurați-vă că o verificați, dar punctele principale ale scrisorii lui Bezos sunt rezumate în următoarele citate din postare:

1) Toate echipele își oferă acum datele și funcționalitatea prin interfețe de servicii.

2) Echipele trebuie să comunice între ele prin aceste interfețe.

3) Sunt interzise alte forme de comunicare între procese: fără legături directe, fără citire directă a datelor unei alte comenzi, fără modele de memorie partajată, fără uși din spate etc. Singura modalitate de interacțiune permisă este accesarea interfeței de serviciu prin rețea.

4) Nu contează ce tehnologie folosesc. HTTP, Corba, Pubsub, protocoale proprietare - nicio diferență. Lui Bezos nu-i pasă.

5) Toate interfețele de service, fără excepție, trebuie să fie proiectate inițial cu capacitatea de a fi controlate extern. Adică, echipa trebuie să planifice și să proiecteze pentru a putea oferi interfața dezvoltatorilor din afara companiei. Fara exceptii.

6) Oricine ignoră aceste cerințe va fi concediat.

SOA este o afacere serioasă. Sigur, există o mulțime de probleme care apar atunci când îl utilizați - consultați această postare despre „lecțiile învățate” de la Amazon - dar are o cantitate incredibilă de beneficii.

Probabil că nu vă veți face prea multe griji cu privire la SOA în timp ce construiți aplicații de jucărie pentru dvs., dar este cu siguranță o problemă care va apărea atunci când începeți să lucrați pentru o companie IT, așa că familiarizarea cu aceasta este o bună practică.

Scopul tău

1. Citiți Secțiunea 7 din Ghidul controlerelor șine pentru a afla despre randarea JSON și XML.
2. Nu sunt obligatorii vizionare (pentru că merg puțin mai departe decât suntem pregătiți în prezent), dar dacă sunteți interesat, aruncați o privire la Railscasts din secțiunea Resurse suplimentare din partea de jos a lecției pentru a afla mai multe despre beneficiile API-ului.

Concluzie

Vom lucra mai îndeaproape cu aplicația dvs. ca API în timpul cursului Javascript. În acest curs, veți crea mai multe aplicații full-stack care utilizează apeluri AJAX pentru o experiență mai bună a utilizatorului, care implică în esență redarea datelor XML sau JSON în loc de o pagină HTML completă. Veți crea apoi mai multe aplicații Javascript cu o singură pagină care se bazează pe API-ul furnizat de aplicația dvs. Rails pentru a prelua toate datele necesare din baza de date, dar, în caz contrar, rulează pe partea client (în browser).

Cel mai bun mod de a înțelege un API este să creați și să interacționați cu el, pe care ne vom concentra în proiectele noastre.

Prin definiția din Wikipedia, un API este un set de clase gata făcute, proceduri, funcții, structuri și constante furnizate de o aplicație (bibliotecă, serviciu) pentru utilizare în produse software externe. Folosit de programatori pentru a scrie tot felul de aplicații.

Dar, deoarece o mare parte din Wikipedia nu este de înțeles pentru mulți oameni, voi încerca să explic în termeni profani ce este un API și pentru ce sunt făcute de obicei și cum sunt utilizate.

API-urile sunt complet diferite, dar ca exemplu, am ales o situație în care avem o rețea de magazine și o singură bază de date comună. Imaginează-ți că deții un program de afiliere. Programul de afiliere funcționează pe următorul principiu: o persoană se înregistrează în programul de afiliere și primește un motor de magazin. Apoi poate instala acest magazin pe gazduirea lui și poate începe să lucreze. Dar toate datele din acest magazin sunt preluate din baza noastră de date, adică trebuie să oferim fiecărui partener acces la prețioasa noastră bază de date. Vă puteți imagina cât de periculos este asta? La urma urmei, trebuie să deschidem accesul la baza de date din exterior, astfel încât toate magazinele partenere să poată lucra cu ea. Ce se întâmplă dacă datele dvs. de acces cad în mâinile infractorilor?

Aici ne va ajuta API-ul. În loc să oferim acces la baza de date, vom realiza pur și simplu un API prin care magazinele partenere vor primi informații. În acest fel, numai scriptul nostru API va funcționa cu baza de date, iar magazinele vor funcționa cu acest script.

Cum functioneaza?
De exemplu, un magazin trimite o solicitare către API-ul nostru
http://ourapi.com/get_books?limit=20
iar API-ul nostru înțelege că trebuie să ofere o listă de cărți formată din 20 de exemplare, deoarece am trecut de parametrul limită egal cu 20. Scriptul nostru (API) face o solicitare la baza de date, primește o listă de cărți și le returnează la stocați (de fapt, se afișează doar ) într-un anumit format. Formatul în care API-ul returnează informații poate fi absolut orice, principalul lucru este că magazinele noastre îl înțeleg. Acesta poate fi JSON, o matrice serializată sau XML. Acest lucru nu mai este important, principalul lucru este că înțelegeți principiul.

Definiți singur setul de comenzi pe care API-ul le înțelege. De exemplu, în cazul nostru, acestea ar putea fi comenzi precum obținerea unei liste de cărți, obținerea unei liste de categorii, obținerea de cărți populare, obținerea de cărți noi etc. În acest fel, chiar dacă un atacator are ocazia să acceseze API-ul nostru, tot ce poate face este să obțină o listă de cărți, iar acest lucru nu reprezintă nicio amenințare pentru baza noastră de date.

Sper că am putut să explic ce este un API cu un exemplu simplu. Dacă aveți întrebări, adresați-le în comentarii sau pe forum și vă vom ajuta cu plăcere să le rezolvați.

Mai devreme sau mai târziu, orice programator se confruntă cu un astfel de concept ca API. Cu toate acestea, atunci când are loc o astfel de întâlnire, nu toată lumea știe ce este, de ce este necesară și cum să o folosească. Și în acest articol voi umple această lacună în cunoștințele unora dintre voi și, de asemenea, voi da un exemplu din practica mea.

API (interfața de programare a aplicației) - Acest interfața de programare a aplicației. În termeni mai simpli, acesta este un set de diferite funcții, constante, clase și formate de interogare care pot fi utilizate în alte programe.

Se poate considera că API- acesta este un anumit obiect, a cărui implementare nu știm, totuși, îl putem folosi. De exemplu, un computer este un obiect a cărui implementare foarte puțină lume o cunoaște, totuși, aproape toată lumea îl poate folosi pentru a efectua anumite acțiuni: vizionarea videoclipurilor, navigarea pe Internet, imprimarea textului etc. Puțini oameni știu cum funcționează totul, dar aproape toată lumea o poate face.

Exemplu API este API Windows, API OpenGL, Direct3D APIși așa mai departe.

De exemplu, nu cu mult timp în urmă am întâlnit și eu direct API. M-am înregistrat pentru serviciul de liste de corespondență" SmartResponder.ru" și a început un buletin informativ, la care oamenii au început să se aboneze. Sarcina a fost următoarea: în 24 de ore de la abonare, o persoană poate achiziționa cursul meu video plătit cu reducere. Deoarece toate informațiile despre abonați sunt stocate pe server " SmartResponder.ru", apoi acces normal (de exemplu, prin DB) Nu am avut acces la aceste date, dar a fost necesar să le implementez. Din fericire, " SmartResponder.ru„ai pe al tău API, pe care l-am folosit.

Am gasit in ele API format de cerere pentru a obține data abonamentului ca rezultat. Mai departe prin răsuci Am trimis cererea corespunzătoare și am primit data de abonament necesară pentru un anumit adrese de email. Urmează procesarea standard și ieșirea rezultatului.

Acest termen scurt este binecunoscut tuturor celor care au cel puțin o oarecare experiență în dezvoltare. Dar nu toată lumea înțelege ce înseamnă exact și de ce este nevoie. Dezvoltator Petru Gazarov a vorbit despre API în cuvinte simple pe blogul său.

Abrevierea API înseamnă „Application Programming Interface” (interfață de programare a aplicației, interfață de programare a aplicației). Majoritatea companiilor mari la un moment dat dezvoltă API-uri pentru clienți sau pentru uz intern. Pentru a înțelege cum și cum sunt utilizate API-urile în dezvoltare și afaceri, mai întâi trebuie să înțelegeți cum funcționează World Wide Web.

World Wide Web și servere la distanță

WWW-ul poate fi gândit ca o rețea uriașă de servere interconectate pe care este stocată fiecare pagină. Un laptop obișnuit poate fi transformat într-un server capabil să deservească un întreg site web în rețea, iar dezvoltatorii folosesc servere locale pentru a crea site-uri web înainte de a le deschide pentru o gamă largă de utilizatori.

Când este introdus în bara de adrese a browserului www.facebook.com O solicitare corespunzătoare este trimisă la serverul Facebook de la distanță. Odată ce browserul primește răspunsul, interpretează codul și afișează pagina.

De fiecare dată când un utilizator vizitează o pagină de pe Internet, el interacționează cu API-ul serverului de la distanță. API-ul este partea componentă a serverului care primește cereri și trimite răspunsuri.

API ca o modalitate de a servi clienții

Multe companii oferă API-uri ca un produs gata făcut. De exemplu, Weather Underground vinde acces la API-ul de date meteo.

Scenariul de utilizare: Pe site-ul unei companii mici există un formular de programare pentru clienți. Compania dorește să integreze Google Calendar în acesta pentru a oferi clienților posibilitatea de a crea automat un eveniment și de a introduce detalii despre o întâlnire viitoare.

Aplicație API: Scopul este ca serverul site-ului să contacteze direct serverul Google cu o solicitare de a crea un eveniment cu detaliile specificate, de a primi răspunsul Google, de a-l procesa și de a trimite informațiile corespunzătoare către browser, de exemplu, un mesaj de confirmare către utilizator. .

Alternativ, browserul poate face o solicitare către API-ul serverului Google fără a trece prin serverul companiei.

Prin ce diferă API-ul Google Calendar de API-ul oricărui alt server la distanță din rețea?

Din punct de vedere tehnic, diferența este în formatul cererii și al răspunsului. Pentru a genera o pagină web completă, browserul așteaptă un răspuns în limbajul de marcare HTML, în timp ce API-ul Google Calendar va returna pur și simplu date într-un format precum JSON.

Dacă o solicitare către API este făcută de serverul site-ului unei companii, atunci acesta este clientul (la fel cum browserul este client atunci când utilizatorul deschide site-ul).

Datorită API-ului, utilizatorul are posibilitatea de a efectua o acțiune fără a părăsi site-ul web al companiei.

Cele mai multe site-uri web moderne folosesc cel puțin câteva API-uri terțe. Multe sarcini au deja soluții gata făcute oferite de dezvoltatori terți, fie că este vorba despre o bibliotecă sau un serviciu. Este adesea mai ușor și mai fiabil să recurgeți la o soluție gata făcută.

Mulți dezvoltatori distribuie aplicația pe mai multe servere, care interacționează între ele folosind API-ul. Serverele care îndeplinesc o funcție de suport pentru serverul principal de aplicații sunt numite microservicii.

Deci, atunci când o companie oferă un API utilizatorilor săi, înseamnă pur și simplu că a creat o serie de adrese URL speciale care returnează doar date ca răspuns.

Astfel de solicitări pot fi adesea trimise printr-un browser. Deoarece transferul de date HTTP are loc sub formă de text, browserul va putea întotdeauna să afișeze răspunsul. De exemplu, printr-un browser puteți accesa direct API-ul GitHub (https://api.github.com/users/petrgazarov), fără un token de acces și puteți primi acest răspuns în format JSON:

Browserul afișează perfect răspunsul JSON, care poate fi inserat în cod. Este suficient de ușor să extragi date dintr-un astfel de text pentru a-l folosi la discreția ta.

Mai multe exemple de API

Cuvântul „aplicare” poate avea semnificații diferite. În contextul API-ului, aceasta înseamnă:

• o bucată de software cu o anumită funcție,
• întregul server, întreaga aplicație sau doar o parte separată a aplicației.

Orice bucată de software care poate fi distinsă clar de mediu poate înlocui litera „A” într-o abreviere în engleză și poate avea, de asemenea, un fel de API. De exemplu, atunci când un dezvoltator implementează o bibliotecă terță parte în cod, aceasta devine parte a întregii aplicații. Ca o bucată de software autonomă, biblioteca va avea un fel de API care îi permite să interacționeze cu restul codului aplicației.

În proiectarea orientată pe obiecte, codul este reprezentat ca o colecție de obiecte. Într-o aplicație, pot exista sute de astfel de obiecte care interacționează între ele. Fiecare dintre ele are propriul set API public proprietăți și metode de interacțiune cu alte obiecte din aplicație. Obiectele pot avea, de asemenea privat, logică internă care este ascunsă de mediu și nu este un API.