O imagine merita o mie de cuvinte …

Acesta este unul dintre motivele pentru care ne place sa reprezentam cele mai complexe idei de software prin imagini si diagrame. Diagramele de clasa si secventa sunt cel mai frecvent intelese, dar exista un numar mare de reprezentari schematice ale diferitelor concepte software si arhitecturale care au crescut in timp. O diagrama ofera in general o imagine de ansamblu usor de digerat a arhitecturii software complexe. Din experienta mea, acest lucru formeaza o baza de intelegere care ajuta foarte mult in timp ce intelegeti acea arhitectura in detaliu.

Array

La fel ca majoritatea oamenilor, imi place foarte mult aceasta abordare. Un domeniu in care m-am straduit sa fac acest lucru si sunt fortat sa intru direct in detalii de nivel scazut este documentatia API. Cand dorim sa consumam un nou API, ni se ofera de obicei o specificatie API. Cel mai probabil, aceasta specificatie este scrisa in Swagger, ceea ce face o treaba buna, descriind detalii la nivel scazut despre ceea ce face fiecare punct final din API. Acest lucru functioneaza destul de bine pentru API-uri foarte simple. Dar, in momentul in care complexitatea API-urilor creste, imi doresc aceasta intelegere de baza a API-ului care face ca scufundarea in detalii sa fie un proces suportabil.

Recent, am incercat sa abordez acest lucru punand o diagrama de ansamblu pentru API-urile furnizate de echipa mea.

Array

Numesc aceasta harta API . M-am inspirat din diagrama clasei, deoarece raspunde frumos la intrebarile pe care le am de obicei cand vad specificatiile API care sunt dincolo de simplitate.

1. Care sunt toate resursele pe care le expune acest API?

2. Cum sunt legate resursele?

3. Cum pot efectua operatiuni importante asupra resurselor cheie?

Dupa cum probabil ati ghicit, harta API se concentreaza in jurul resurselor , un principiu central al REST. Reprezentarea diagrama pe care am folosit-o pentru o resursa este foarte apropiata de o clasa cu cateva diferente evidente.

Array

Scheletul unei reprezentari a resurselor intr-o harta API

Are un nume de resurse si o descriere a resursei. Acest lucru poate fi copiat din specificatiile API-ului dvs., din motive de coerenta. Apoi enumera toate punctele finale din jurul resursei grupate dupa patru verbe HTTP principale pe care le folosim in API-urile REST – GET, POST, PUT si DELETE. Acest lucru nu este prescriptiv. Daca o resursa nu are niciun punct final DELETE, atunci nu as avea o sectiune DELETE pe diagrama mea. In mod similar, daca utilizati alte verbe HTTP, atunci nu ezitati sa le adaugati.

In continuare, la verb, mentionam adresele URL ale punctelor finale care corespund acelui verb. Acesta este un camp de text gratuit, fara un mod prescris de modul in care furnizam aceste informatii. Putem fi la fel de creativi pe cat ne dorim aici.

Sa folosim un exemplu de API pentru o biblioteca. Este suficient de simplu pentru o postare pe blog. Intr-un simplu API de biblioteca, ati avea carti, autori, membri si inchirierile acestora. O resursa de carte dintr-o harta API poate arata ca mai jos.

Reprezentarea resursei de carte in Harta API

Acesta este un API CRUD foarte standard. Exista mai multe modalitati de a obtine o carte care este listata. Un lucru interesant este sa obtineti toate cartile scrise de un autor. Vom vizita din nou acest punct final in sectiunea urmatoare despre relatii. Acest punct final este capturat sub resursa carte, deoarece punctul final returneaza o lista de carti.

Sa ne uitam la relatiile urmatoare. Exista o relatie bidirectionala intre o carte si un autor. O carte are unul sau mai multi autori. Un autor are una sau mai multe carti. Sa presupunem ca am decis sa nu sustinem relatia bidirectionala in API-urile noastre. Sustinem doar relatia „autorul are una sau mai multe carti”. Aceasta relatie este intruchipata in punctul final / autor / {id} / carti care returneaza toate cartile scrise de autor care au specificat id. Aceasta este listata sub resursa de carte, deoarece returneaza o lista de carti. Cu toate acestea, fara un ajutor vizual, aflarea unor astfel de relatii prin scanarea tuturor punctelor finale pe o harta API relativ mai mare este o provocare. Deci, folosim linii cu sageti si text pentru a reprezenta o astfel de relatie.

Relatia dintre doua resurse reprezentate vizual intr-o harta API

In loc sa trasam o linie aleatorie de la o resursa la alta, le trasam cat mai aproape posibil de punctul final in cauza. Acest lucru face mai usor sa aflati ce punct final reprezinta relatia respectiva.

Punctul final al autorului ar putea fi modelat complet diferit. De exemplu, este posibil sa nu expuneti niciodata un punct final pentru a adauga in mod explicit autori, deoarece acestea sunt automat atunci cand este adaugata o carte. Acelasi lucru se aplica stergerii autorilor.

Asta este cu adevarat. Asa arata o harta API completa pentru API-ul nostru simplu de biblioteca.

Uneori exista o relatie indirecta intre doua resurse. In exemplul nostru, membrii au o relatie indirecta cu cartile atunci cand inchiriaza carti. Aceasta relatie se face printr-o resursa de inchiriere. Daca merita sa subliniem relatia indirecta, atunci vom folosi o linie punctata pentru ao reprezenta, toate celelalte conventii fiind aceleasi.

Nu va voi da vina daca ati simti ca aceasta este doar o diagrama ER pentru API-uri. Exemplul de biblioteca simpla cu metodele API de tip CRUD este in mare parte de vina. Cu toate acestea, daca API-ul dvs. este proiectat sa fie CRUD, atunci harta dvs. API va arata similar cu o diagrama ER. Acesta este inca un lucru bun, deoarece Harta API scoate la suprafata faptul ca API-ul este conceput asa, in mod intentionat sau neintentionat. Dar revenind la intrebarea initiala – Harta API este intr-adevar doar o diagrama ER pentru API? Ganditi-va la urmatoarele

  • O diagrama ER descrie structura tabelelor. Harta API nu se concentreaza pe structura resurselor.
  • Singura relatie intre entitati pe care o diagrama ER o descrie este cea a cardinalitatii. Intr-o harta API, pe langa cardinalitate, puteti utiliza un descriptor de relatii bogate, deoarece este doar un text liber.
  • Intr-un sens traditional, o diagrama ER este un instrument de proiectare. V-ati proiecta bazele de date folosind o diagrama ER si apoi ati construi scripturile DDL reale din ea, cu exceptia cazului in care ati generat automat DDL-ul dvs. utilizand un ORM. Harta API nu este un instrument de proiectare. Descrie doar un API dupa ce este implementat.
  • O diagrama ER documenteaza structura entitatilor si relatiile dintre ele, dar nu vorbeste despre modul in care puteti interactiona cu acele entitati, de exemplu prin intermediul procedurilor stocate, functiilor si declansatorilor. API Map, pe de alta parte, pune accentul pe metodele API prin care consumatorii interactioneaza cu resursele. In calitate de consumator API, daca nu puteti accesa sau modifica o resursa prin una dintre metodele API descrise, atunci nu puteti accesa sau modifica resursa respectiva.

Diagrama API are unele asemanari cu diagrama ER, dar intentia sa este foarte diferita de cea a unei diagrame ER. Acestea fiind spuse, ar fi util sa va inspirati dintr-o diagrama ER pentru a imbunatati API Map. Putem folosi notatiile cardinalitatii standard din diagrama ER daca acest lucru ajuta. Daca credeti ca va va ajuta sa includeti atribute importante pe resurse intr-o harta API, asa cum face diagrama ER, nu ezitati sa faceti si asta. Nu cred ca este vorba daca API Map este doar o diagrama ER sau nu. Este vorba despre ce valoare adauga API Map si, in opinia mea, adauga valoare.

Acest lucru are inca unele lacune, cu toate acestea, m-a ajutat enorm sa introduc API-uri complexe noilor dezvoltatori intr-un mod mai bland. De obicei le arat noilor dezvoltatori o harta API inainte de a le arunca in specificatii complexe. Singura provocare cu care m-am confruntat pana acum este ca trasarea acestei diagrame poate consuma mult timp daca incercati sa utilizati instrumente de diagramare standard. Trebuie sa redimensionati si sa miscati formele pentru a incadra tot textul si a stiva formele unul langa celalalt frumos. Visio face o treaba excelenta la acest lucru si este instrumentul meu de alegere. Un desen manual ar trebui, de asemenea, sa judece bine aceasta diagrama.

Ce folositi pentru a va reprezenta vizual API-urile? Anunta-ma prin comentarii.

ARTICOLE SIMILAREDE LA ACELAȘI AUTOR