Sări la conținutul principal

V1 vs V2 - Versiuni API

Qarta oferă două versiuni ale punctelor finale de analiză portofoliu. Înțelegerea diferențelor este crucială pentru a alege versiunea potrivită pentru integrarea ta.

Prezentare generală​

AspectV1V2
Cale de bază/graph/api/v1//graph/api/v2/
Model filtruSimplu: {field, value}Recursiv: {field, value, filters[]}
Metoda de căutareGET cu parametri de interogarePOST cu corp JSON
Când să utilizeziFiltre simpleFiltre complexe, imbricați
Data lansăriiOriginalVersiune îmbunătățită

Diferențe cheie​

1. Model filtru​

Diferența fundamentală între V1 și V2 este modul în care sunt structurate filtrele.

V1 - Filtre plate simple

{
  "source": "portfolio_01",
  "filters": [
    {"field": "oe_id", "value": "prop_123"},
    {"field": "property_type", "value": "residential"},
    {"field": "occupancy", "value": "occupied"}
  ]
}
  • Fiecare filtru este o pereche simplă {field, value}
  • Toate filtrele sunt combinate cu AND
  • Nu poate exprima logică complexă imbricată

V2 - Filtre imbricate recursive

{
  "source": "portfolio_01",
  "filters_v2": [
    {
      "field": "property_type",
      "value": "residential",
      "filters": [
        {"field": "occupancy", "value": "occupied"},
        {"field": "price", "value": "500000"}
      ]
    },
    {"field": "oe_id", "value": "prop_123"}
  ]
}
  • Fiecare filtru poate avea sub-filtre imbricate filters[]
  • Suportă combinații logice complexe
  • Mai expresiv și mai puternic

2. Metoda HTTP a endpoint-ului de căutare​

Punctele finale V1 și V2 de căutare utilizează metode HTTP diferite:

V1 - Cerere GET

GET /graph/api/v1/reports/portfolio/entries/selection/search?filters={...}&columns=name,value&source=portfolio_01
  • Cerere GET cu parametri de interogare
  • JSON filtru este codat în URL-ul șir de interogare
  • Limitat de constrângerile lungimii URL

V2 - Cerere POST

POST /graph/api/v2/reports/portfolio/entries/selection/search
Content-Type: application/json

{
  "filters": [...],
  "columns": ["name", "value"],
  "source": "portfolio_01"
}
  • Cerere POST cu corp JSON
  • Nu există limitări de lungime URL
  • Structură de cerere mai curată

3. Selecția punctelor și intrărilor​

Toate punctele finale portofoliu au schimbat formatul filtru dar au păstrat aceleași metode HTTP:

EndpointV1V2Schimbare
Puncte în selecțiePOSTPOSTDoar format filtru
Puncte în bufferPOSTPOSTDoar format filtru
Intrări în selecțiePOSTPOSTDoar format filtru
Intrări în bufferPOSTPOSTDoar format filtru
Căutare puncteGET → filters paramPOST → filters_v2 bodyMetoda + format
Căutare intrăriGET → filters paramPOST → filters_v2 bodyMetoda + format

Când să utilizezi fiecare versiune​

Utilizează V1 dacă:​

  • ✅ Ai cerințe de filtru simple și plate
  • ✅ Nu migrezi integrări existente
  • ✅ Filtrele tale nu necesită logică imbricată
  • ✅ Exemplu: "Arată-mi toate proprietățile rezidențiale din portofoliu"

Utilizează V2 dacă:​

  • ✅ Ai nevoie de logică filtru imbricată sau complexă
  • ✅ Construiești integrări noi
  • ✅ Vrei interogări mai expresive
  • ✅ Exemplu: "Arată-mi proprietățile rezidențiale ocupate unde preț > $500k ȘI locație în zona de cărări"

Migrare de la V1 la V2​

Dacă migrezi de la V1 la V2, iată ce se schimbă:

1. Actualizează calea API​

# V1
GET /graph/api/v1/reports/portfolio/points/selection

# V2
POST /graph/api/v2/reports/portfolio/points/selection

2. Actualizează formatul filtru​

Înainte (V1):

{
  "source": "portfolio_01",
  "filters": [
    {"field": "oe_id", "value": "abc123"},
    {"field": "property_type", "value": "residential"}
  ]
}

După (V2):

{
  "source": "portfolio_01",
  "filters_v2": [
    {"field": "oe_id", "value": "abc123"},
    {"field": "property_type", "value": "residential"}
  ]
}
  • Redenumește filters → filters_v2
  • Formatul filtru individual rămâne același (pentru filtre plate)
  • Poți acum adăuga sub-filtre imbricate filters[] dacă este necesar

3. Actualizează apelurile endpoint-ului de căutare​

Înainte (V1):

curl -X GET "https://graph.quarticle.ro/graph/api/v1/reports/portfolio/entries/selection/search" \
  -H "Authorization: YOUR_API_KEY" \
  -d "filters={\"field\":\"oe_id\",\"value\":\"abc123\"}&columns=name,value&source=portfolio_01"

După (V2):

curl -X POST "https://graph.quarticle.ro/graph/api/v2/reports/portfolio/entries/selection/search" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [{"field": "oe_id", "value": "abc123"}],
    "columns": ["name", "value"],
    "source": "portfolio_01"
  }'
  • Schimbă la cerere POST
  • Mută parametrii de interogare la corpul JSON
Excepție endpoint de căutare

Căutarea endpoint-urilor V2 (entries/selection/search și points/selection/search) utilizează filters — nu filters_v2 — în corpul cererii. Aceasta se datorează faptului că filtrele de căutare sunt trimise ca o listă plată în corpul JSON (nu imbricată în wrapper-ul params utilizat de punctele finale de selecție). Toate celelalte puncte finale V2 utilizează filters_v2.

Exemplu filtru complex​

Iată un exemplu din lumea reală care arată puterea filtrului imbricat V2:

Scenariu: Găsești proprietăți rezidențiale ocupate în piețe prime cu tranzacții recente

Interogare V2:

{
  "source": "portfolio_01",
  "filters_v2": [
    {
      "field": "property_type",
      "value": "residential",
      "filters": [
        {
          "field": "market_tier",
          "value": "prime",
          "filters": [
            {"field": "occupancy", "value": "occupied"},
            {"field": "transaction_within_months", "value": "12"}
          ]
        }
      ]
    }
  ]
}

Aceasta ar fi dificil de exprimat în structura filtrului plat V1.

Alte puncte finale​

Negrăbit de diviziunea V1/V2:

  • Servicii de locație (geocodificare, geocodificare inversă, completare automată)
  • Raportare riscuri (utilizează puncte finale separate cu propria versiune)
  • Puncte finale îmbogățire
  • Servicii WMS/WFS

Compatibilitate înapoi​

Punctele finale V1 vor continua să fie susținute. Nu există o dată dură pentru deprecierea V1. Poți migra la propriul ritm.

Ai nevoie de ajutor?​