REST API: padparameters

Elk REST-endpoint van Personyze deelt dezelfde syntaxis voor padparameters om te filteren, kolommen te selecteren, te sorteren en resultaten te begrenzen. Dezelfde modifiers — where, columns, column, order_by, order_by_desc, limit — werken bij alle objecten op dezelfde manier, met één verkorte vorm voor opzoekingen op de primaire sleutel.

Vereisten: REST API: overzicht en Authenticatie — daar worden de vorm van de URL en de inloggegevens uitgelegd.

Algemene vorm van de URL

Na de objectnaam is het URL-pad een reeks /<modifier>/<value>/... -paren:

/rest/<object>/[<id>|]<modifier>/<value>/<modifier>/<value>/...

Opmerkingen:

• De volgorde maakt niet uit. /limit/100/where/x=y is gelijk aan /where/x=y/limit/100.
• Elke modifier komt hooguit één keer voor per verzoek. Meerdere where -voorwaarden komen in één where/ -segment, met de operatoren & en | (zie hieronder).
• Waarden worden URL-gedecodeerd voordat ze worden verwerkt — dus een kolomwaarde met /, =, &, of % moet procent-gecodeerd zijn.

Vorm met één id (opzoeken op primaire sleutel)

Een los numeriek segment op de eerste positie is een opzoeking op de primaire sleutel:

GET /rest/<object>/<id>

Dit geeft één record terug (een object, geen array met één element), of 400 Row not found als de ID niet bestaat.

GET /rest/placeholders/14
GET /rest/users/57291                    # PK = user_id

Gebruik voor opzoekingen op een externe identificator (je SKU, CRM-ID, enz.) de where -vorm met internal_id:

GET /rest/users/where/internal_id=42
GET /rest/products/where/internal_id=SKU-1234

where — filteren

Filtert de resultaten. De eenvoudigste vorm is where/<column><op><value>:

Voorwaarden combineren met & (EN) en | (OF)

where/<cond1>&<cond2>          # both must match (AND)
where/<cond1>|<cond2>          # either matches (OR)
where/<a>&<b>|<c>&<d>          # (a AND b) OR (c AND d) — & binds tighter than |

Voorbeelden:

where/status=active&age_from>=18
where/email=alice@example.com|email=bob@example.com
where/category:books,tools&is_in_stock=yes

Vereiste geïndexeerde kolom

REST-endpoints rond grote tabellen (users, events, sessions_archive, summary_actions, enz.) weigeren query’s waarvan de where of order_by geen index gebruikt. De foutmelding noemt de geïndexeerde kolommen die het endpoint beschikbaar stelt:

Cannot do this operation on whole table: column "uset_id" is not indexed.
Please, use "where" condition or order by an indexed column
(user_id, last_session_time, data_last_modified, fb_id, email, internal_id).

Samengestelde indexen verschijnen in de vorm [col1, col2, col3] . Alleen de eerste kolom van een samengestelde index is bruikbaar als filter op één kolom:

... or order by an indexed column
(user_id, [product_internal_id, user_id, transaction_time], status, time).

Hier gebruikt where/product_internal_id=... de samengestelde index, maar where/transaction_time>... op zichzelf niet — dat is de derde kolom van de samengestelde index, alleen nuttig in combinatie met product_internal_id en user_id.

columns — specifieke kolommen selecteren

Beperk de geselecteerde kolommen. Lijst gescheiden door komma’s. Standaard zijn dat “alle gedocumenteerde kolommen” van het object.

GET /rest/users/where/internal_id=42/columns/user_id,first_name,last_name

Onbekende kolommen: bij objecten die dynamische kolomnamen ondersteunen (users, articles, products) worden onbekende kolommen teruggegeven als null. Bij objecten met een vast schema krijg je 400 Unknown column.

column (enkelvoud) — platte array met waarden

Verkorte vorm voor “selecteer één kolom en geef een platte array met waarden terug” in plaats van een array met objecten.

GET /rest/users/where/last_session_time>1700000000/column/email
→ ["alice@example.com", "bob@example.com", ...]

Vergeleken met de meervoudsvorm columns :

GET /rest/users/where/last_session_time>1700000000/columns/email
→ [{"email":"alice@example.com"}, {"email":"bob@example.com"}, ...]

Handig als je het resultaat direct wilt doorgeven aan een ander systeem dat een lijst verwacht (bijv. een doelgroepexport bouwen, e-mailadressen ontdubbelen).

order_by / order_by_desc

order_by/<col>[,<col>...]          # ascending
order_by_desc/<col>[,<col>...]     # descending

Meerdere kolommen: bij gelijke waarden in de eerste kolom beslist de tweede, enzovoort. Elke richting (order_by of order_by_desc) geldt voor alle genoemde kolommen.

GET /rest/users/order_by_desc/last_session_time/limit/100

De eerstgenoemde kolom moet een geïndexeerde kolom zijn (of de eerste kolom van een samengestelde index) als er geen where -clausule is — anders weigert het endpoint het verzoek als scan van de volledige tabel.

limit — paginering

limit/<count>                      # first <count> rows
limit/<offset>,<count>             # skip <offset> then take <count>

De harde limiet is 1.000 rijen per verzoek. Grotere waarden worden geweigerd met 400 Only can select up to 1000 rows.

GET /rest/users/order_by_desc/last_session_time/limit/100
GET /rest/users/order_by_desc/last_session_time/limit/100,100   # rows 100..199

Cursorpaginering — de voorkeur bij grote resultatensets

Diepe offset -waarden worden traag, omdat de database alle overgeslagen rijen opnieuw moet lezen. Pagineer bij grotere resultatensets door de geïndexeerde order_by -kolom in cursorstijl te doorlopen met where:

# page 1
GET /rest/users/order_by_desc/last_session_time/limit/1000

# page 2 — pass the last seen value
GET /rest/users/where/last_session_time<1730000000/order_by_desc/last_session_time/limit/1000

# page 3 — pass the last seen value from page 2
GET /rest/users/where/last_session_time<1729000000/order_by_desc/last_session_time/limit/1000

De cursorwaarde is de waarde die het laatste record van de vorige pagina in de geïndexeerde kolom had. Dit blijft altijd snel — elke pagina is een scan van een geïndexeerd bereik, geen lineaire scan die “50.000 rijen overslaat”.

Alles samen

GET /rest/products
        /where/category=tools&is_in_stock=yes
        /columns/id,internal_id,title,price,inventory
        /order_by/title
        /limit/100

(Regeleinden toegevoegd voor de leesbaarheid — in werkelijkheid staat alles op één regel, zonder spaties.)

Volgende stappen