Vezi si: Foaie de trucuri pentru construirea platformei

  1. Construiti API-ul avand in vedere consumatorii – ca produs in sine.

    • Nu pentru o anumita interfata de utilizare.
    • Imbratisati flexibilitatea / ajustabilitatea fiecarui punct final (a se vedea # 5, 6 si 7).
    • Mananca-ti propria proba pentru caini, chiar daca trebuie sa faci o macheta cu un exemplu de interfata.

  2. Utilizati metafora colectiei.

    • Doua adrese URL (puncte finale) pe resursa:
      • Colectarea resurselor (de ex. / Comenzi)
      • Resursa individuala din colectie (de ex. / Orders / {orderId}).
    • Folositi forme de plural („ordine” in loc de „ordine”).
    • Alterneaza numele resurselor cu ID-uri ca noduri URL (de ex. / Orders / {orderId} / items / {itemId})
    • Pastrati adresele URL cat mai scurte posibil. De preferinta, nu mai mult de trei noduri pe URL.

  3. Utilizati substantive ca nume de resurse (de exemplu, nu utilizati verbe in URL-uri).

  4. Faceti semnificative reprezentarile resurselor.

    • „Fara ID-uri goale!” Nu exista ID-uri simple incorporate in raspunsuri. Utilizati linkuri si obiecte de referinta.
    • Proiectati reprezentari ale resurselor. Nu reprezentati pur si simplu tabele de baze de date.
    • Fuzionati reprezentari. Nu expuneti tabelele de relatii ca doua ID-uri.

  5. Sprijina filtrarea, sortarea si paginarea colectiilor.

  6. Sprijinirea extinderii legaturilor de relatii. Permiteti clientilor sa extinda datele continute in raspuns, incluzand reprezentari suplimentare in loc de linkuri sau in plus fata de acestea.

  7. Sprijiniti proiectiile pe teren despre resurse. Permiteti clientilor sa reduca numarul campurilor care revin in raspuns.

  8. Utilizati numele metodelor HTTP pentru a insemna ceva:

    • POST – creati si alte operatii non-idempotente.
    • PUT – actualizare.
    • GET – cititi o resursa sau o colectie.
    • DELETE – stergeti o resursa sau o colectie.

  9. Utilizati coduri de stare HTTP pentru a fi semnificativ.

  10. Utilizati formatele de timp ISO 8601 pentru date in reprezentari.

  11. Luati in considerare conexiunea utilizand o strategie de conectare. Cateva exemple populare sunt:

    • HAL
    • Sirena
    • JSON-LD
    • Colectie + JSON

  12. Utilizati OAuth2 pentru a va securiza API-ul.

    • Utilizati un simbol Purtator pentru autentificare.
    • Solicitati HTTPS / TLS / SSL pentru a va accesa API-urile. Jetoanele OAuth2 Bearer o cer. Comunicarea necriptata prin HTTP permite ascultarea si uzurparea simpla.

  13. Utilizati negocierea de tip continut pentru a descrie sarcinile utile ale solicitarilor primite.

    De exemplu, sa presupunem ca faceti evaluari, inclusiv o evaluare degetul mare in sus / degetul mic in jos si de cinci stele. Aveti un singur traseu pentru a crea o evaluare: POST / evaluari

    Cum distingeti datele primite de serviciu, astfel incat sa poata determina ce tip de evaluare este: degetul mare sau cinci stele?

    Tentatia este de a crea un traseu pentru fiecare tip de rating: POST / rating / five_star si POST / ratings / thumbs_up

    Cu toate acestea, folosind negocierea tipului de continut, putem folosi aceeasi ruta POST / evaluari pentru ambele tipuri. Prin setarea antetului Content-Type la cerere la ceva de genul Content-Type: application / vnd.company.rating.thumbsup sau Content-Type: application / vnd.company.rating.fivestar , serverul poate determina cum sa proceseze evaluarea primita date.

  14. Evolutie asupra versiunilor. Cu toate acestea, daca faceti versiuni, utilizati antetul Accept in loc de versiune in adresa URL.

    • Versiunea prin URL inseamna o versiune „platforma” si intreaga platforma trebuie versionata in acelasi timp pentru a permite strategia de conectare.
    • Versiunea prin antetul Accept este versiunea resursei.
    • Adaugarile la un raspuns JSON nu necesita versiuni. Cu toate acestea, adaugirile la un corp de solicitare JSON care sunt „necesare” sunt suparatoare – si pot necesita versiuni.
    • Conectarea si versiunea hipermedia sunt dificile, indiferent de ce – minimizati-le.
    • Retineti ca o versiune din adresa URL, desi este descurajata, poate fi utilizata ca versiune „platforma”. Ar trebui sa apara ca primul nod din cale si nu sa versioneze diferit punctele finale individuale (de exemplu, api.example.com/v1 / …).

  15. Luati in considerare capacitatea de cache. Folositi cel putin urmatoarele anteturi de raspuns:

    • ETag – Un sir arbitrar pentru versiunea unei reprezentari. Asigurati-va ca includeti tipul media in valoarea hash, deoarece aceasta face o reprezentare diferita. (ex: ETag: “686897696a7c876b7e”)
    • Data – Data si ora raspunsului a fost returnat (in format RFC1123). (ex: Data: Duminica, 06 noiembrie 1994 08:49:37 GMT)
    • Cache-Control – Numarul maxim de secunde (varsta maxima) poate fi memorat in cache. Cu toate acestea, daca cache-ul nu este acceptat pentru raspuns, atunci no-cache este valoarea. (de exemplu: Cache-Control: 360 sau Cache-Control: no-cache)
    • Expira – Daca este data varsta maxima, contine marcajul de timp (in format RFC1123) pentru momentul in care expira raspunsul, care este valoarea Datei (de ex. Acum) plus varsta maxima. Daca cache-ul nu este acceptat pentru raspuns, acest antet nu este prezent. (ex: Expira: Duminica, 06 noiembrie 1994 08:49:37 GMT)
    • Pragma – Cand Cache-Control este „no-cache”, acest antet este setat si la „no-cache”. In caz contrar, nu este prezent. (ex: Pragma: no-cache)
    • Last-Modified – Marcajul de timp in care resursa a fost modificata ultima data (in format RFC1123). (ex: Ultima modificare: Duminica, 06 noiembrie 1994 08:49:37 GMT)

  16. Asigurati-va ca operatiunile dvs. GET, PUT si DELETE sunt idempotente. Nu ar trebui sa existe efecte adverse secundare din operatiuni.

ARTICOLE SIMILAREDE LA ACELAȘI AUTOR