Șase feluri de a folosi date pe care nu le întreții.
Orice set de date, oricât de diferit ar fi conținutul lui, ajunge să facă în produsul tău unul din câteva lucruri: să confirme, să sugereze, să completeze, să calculeze, să grupeze sau să spună cum era înainte.
Pagina asta e despre acele șase forme. Ce set de date le rezolvă în cazul tău alegi din catalog.
GET /{modul}/v1/{resursă}?pagina=1
Authorization: Bearer …
{
"data": // singurul lucru care diferă între seturi
"meta": // total, paginare, vechimea datelor
"links": // pagina următoare, dacă există
}
Șase forme. Restul sunt combinații.
Se aplică oricărui set din catalog și oricăruia dintre cele care vor urma. Dacă recunoști una dintre ele în produsul tău, ai deja cazul de utilizare.
Confirmi că o valoare introdusă de utilizator există cu adevărat în setul oficial și e ceea ce pretinde. Verificarea se face la introducere, când corectarea costă un clic — nu mai târziu, când costă altceva.
Câmpul propune rezultate în timp ce utilizatorul tastează, dintr-un set oficial, nu dintr-o listă statică ținută local. Ce ajunge în baza ta e o valoare aleasă dintr-o mulțime închisă, nu text liber.
Un singur identificator introdus aduce restul informațiilor. Utilizatorul tastează mai puțin, datele intră scrise corect de la început, iar tu nu mai cureți în aval ce s-a introdus greșit în amonte.
Uneori nu ai nevoie de înregistrare, ci de rezultat. Răspunsul vine deja calculat, cu regulile aplicate corect, ca să nu reimplementezi o logică pe care ar trebui apoi s-o ții la zi.
Rapoartele se construiesc pe coduri stabile, nu pe denumiri scrise de mână. Trei variante de scriere ale aceluiași lucru ajung în același rând, pentru că nu mai compari șiruri de caractere.
Nu doar cum e acum, ci cum era la o dată anume. Pentru orice decizie care trebuie justificată ulterior, întrebarea corectă e ce era valabil atunci, nu ce e valabil azi.
Oricare dintre ele, în masă.
Trimiți multe valori într-un singur apel, în loc de un apel pentru fiecare. Un job programat care trece toată baza ta prin catalog costă zeci de requesturi, nu zeci de mii — de aici vine diferența dintre o verificare lunară și una zilnică.
Un răspuns util e, de obicei, două apeluri.
Seturile sunt independente, dar se leagă prin coduri. Un rezultat devine parametrul următorului apel, iar întrebarea reală primește răspuns fără să ții nimic local.
Întrebi setul care conține identificatorul
Primești înregistrarea completă, cu toate câmpurile ei — inclusiv codurile prin care e legată de alte seturi.
GET /{modul-a}/v1/{resursă}/{id}
Iei codul de legătură din răspuns
E un câmp obișnuit, documentat în schema modulului. Nu trebuie construit, ghicit sau normalizat.
"data": { …, "cod_legatura": … }
Îl folosești ca parametru în al doilea set
Al doilea apel e aproape întotdeauna servit din cache, deci costul real al compunerii e neglijabil.
GET /{modul-b}/v1/{resursă}?cod=…
Fără compunere ai avea două integrări care nu-și vorbesc și ar trebui să construiești tu puntea dintre ele — exact munca pe care încerci s-o eviți.
Poți folosi un singur set și ignora restul catalogului; nimic nu te forțează să adopți mai mult decât ai nevoie. Dar când ai nevoie, legătura există deja.
Ai un lanț care nu ți-e clar? Scrie-ne ce încerci să afli și îți trimitem varianta cea mai ieftină în requesturi.
Întreabă-neEchipe care depind de date întreținute de altcineva.
Aceleași șase forme, văzute din unghiul câtorva feluri de produse.
Câmpurile se completează din identificator, iar ce introduce utilizatorul e confirmat înainte să ajungă într-un document.
Valori alese din sugestii în loc de tastate liber: mai puține comenzi blocate și rapoarte fără curățare manuală.
Verificare la înrolare, calcule pe date oficiale și posibilitatea de a arăta ce era valabil în momentul deciziei.
Valori normalizate pe coduri stabile înainte de planificare, agregări pe aceeași ierarhie oficială ca rapoartele.
O căutare, o sugestie, un total calculat — funcții simple care se sprijină pe un set pe care nimeni nu vrea să-l întrețină.
Dimensiuni gata normalizate pentru warehouse, cu coduri care nu se schimbă între rulări. Join-uri reproductibile.
Un singur strat de integrare, refolosit la toți clienții. Versionarea per modul face ca un upgrade să nu atingă restul.
Fiecare modul are pagina lui, cu endpointurile, schema și cazurile specifice.
Vezi catalogul →Costul nu e integrarea. E întreținerea.
Un import se scrie într-o după-amiază. Problema începe în luna a patra, când sursa își schimbă formatul într-o vineri seara.
Majoritatea răspunsurilor vin din cache, nu din baza de date.
Cu validare condiționată nu consumi din cotă dacă datele n-au variat.
Cât rămâne activă o versiune veche de modul, minimum, după anunț.
Un token și clientul HTTP pe care îl ai deja.
Nu instalezi nimic. Dacă vrei un client tipat, îl generezi din specificația OpenAPI a modulului, în limbajul tău.
# orice modul, aceeași formă
curl "https://oneapi.ro/api/{modul}/v1/{resursă}" \
-H "Authorization: Bearer $ONEAPI_TOKEN" \
-H "Accept: application/json"
# a doua oară, fără consum din cotă
curl "https://oneapi.ro/api/{modul}/v1/{resursă}" \
-H "Authorization: Bearer $ONEAPI_TOKEN" \
-H 'If-None-Match: "a3f9c1e0"'
# → 304 Not Modified
O singură formă de eroare, în tot catalogul.
Codul e stabil și documentat, mesajul e pentru om, câmpul îți spune ce parametru să corectezi, iar identificatorul cererii e ce ne trimiți nouă dacă ai nevoie de ajutor.
HTTP/1.1 422 Unprocessable Content
{ "error": {
"cod": "parametru_invalid",
"mesaj": "Valoarea nu e acceptată.",
"camp": "…",
"request_id": "req_01JZQ8M2"
} }
Înainte să scrii primul request.
Restul, în întrebări frecvente și în documentație.