AEPs: Cum să standardizezi API-urile fără să înnebunești

Dacă ai încercat vreodată să conectezi două microservicii de la echipe diferite și te-ai simțit ca un diplomat la negocieri — avem vești bune pentru tine.

Google a lansat AEPs (API Enhancement Proposals) — un repozitoriu deschis cu recomandări pentru proiectarea API-urilor. Pe scurt, e ca PEP pentru Python, dar pentru API-uri. Acum, în loc să inventezi roata cu colțuri pătrate de fiecare dată, poți să te uiți în AEPs și să afli cum să numești un endpoint, ce coduri de stare să returnezi și cum să eviți greșelile comune.

Primul lucru care sare în ochi — AEPs nu e doar o listă de reguli, ci un document viu cu discuții. Poți propune propriul AEP dacă descoperi că problema ta nu e încă acoperită. Pregătește-te însă pentru un code review care poate dura câteva săptămâni — dar e mai bine decât să rescrii jumătate din backend mai târziu.

Ce conține?

• Denumirea: cum să numești resursele ca să nu confunzi users cu user-profiles.
• Erori standard: 404, 409, 429 — totul e deja documentat, nu mai trebuie să inventezi coduri proprii.
• Paginație: în sfârșit o abordare unitară pentru cursor-based și offset-based.
• Versionare: spoiler: v1, v2 nu sunt întotdeauna o idee bună.

Desigur, AEPs nu sunt un panaceu. Dacă echipa ta preferă să hardcodeze numere magice — niciun repozitoriu nu te va salva. Dar pentru startup-uri și proiecte mature, e o bază excelentă pentru a nu reinventa roata și a nu te certa la code review.

Comentariul studioului METABYTE: La METABYTE ne place ordinea — mai ales când API-urile sunt scrise după standarde unitare. AEPs te vor ajuta să nu pierzi timpul cu dispute „cum să numim acest endpoint" și să te concentrezi pe logica de business reală. Deși, recunoaștem, uneori și noi folosim numere magice — dar doar când nu se uită nimeni.