Virtour REST API

Végpontok

Az alap URL az API-hoz a https://api.virtour.hu/, melyet egy útvonal követ az adott végponthoz, melyek alább lesznek részletezve:

HTTP method	Útvonal	Leírás
GET	/advertisements	Az összes hirdetés elérése.
GET	/media	Az összes médiafájl adatainak elérése.
GET	/media-directories	Az összes média könyvtár adatainak elérése.
GET	/news	Az összes hír elérése.
GET	/providers	Az összes szolgáltató elérése.
GET	/regions	Az összes térség elérése.
GET	/routes	Az összes túraútvonal elérése.
GET	/route-types	Az összes túraútvonal típus elérése.
GET	/services	Az összes szolgáltatás típus elérése.

A fent leírt végpontokat kiegészíthetjük egy adott rekord azonosítójával, így csak a kiválasztott rekord adatai jelennek meg.
Pl.: https://api.virtour.hu/providers/25 - Az alábbi végponton találhatóak a 25-ös id-val rendelkező szolgáltató adatai.
Értelemszerűen ezeken a végpontokon nem használhatóak a lekérdezéses paraméterek, a language paramétert leszámítva.

A visszakapott adatok formátuma meghatározható azáltal, hogy megadjuk a fájlkiterjesztést a végpont útvonal végén.
Pl.: https://api.virtour.hu/providers.xml, vagy https://api.virtour.hu/providers.json. Az alapértelmezett formátum a json.

A http request method felülírható a lekérdezésben megadott _method paraméterrel vagy az X-HTTP-Method-Override request header-rel. Így például POST method-dal is lekérdezhető minden adat.

Hitelesítés

Az API akkor küld megfelelő választ a request-ekre, ha a request tartalmazza a key paramétert, melynek az értéke egy érvényes, a kliens ip-címéhez tartozó kulcs. Kulcsot az API üzemeltetőjétől kérhet.

Lekérdezések

A végpontok meghívásakor lekérdezési paraméterekkel lehet pontosítani a találati listánkat, az igényeinknek megfelelően. A Lekérdezések fejezetben ezeket a paramétereket részletezzük.

Keresés és szűrés

Keresési vagy szűrési kifejezések megadásával szűkíthetjük a találati listát.

név: filter
típus: array
alapértelmezett érték: null

A filter paraméter egy szűrő kifelyezéseket tartalmazó tömb. A tömb első elemeként megadható a szűrő kifejezések közötti reláció, melyet az API-nak a lekérdeznéskor alkalmaznia kell. A reláció értéke lehet AND, vagy OR, típusa pedig string, az alapértelmezett relácó az AND. A filter tömbben a reláció után kétféle elem típus adható meg:

Szűrő kifejezés

típus: object

Egy szűrő kifejezés a következő paramétereket tartalmazza:

Név Típus Leírás

field string | array Egy vagy több mező nevének megadása, melyben a szűrő kifejezésre keresünk a lekérdezéskor.
Érvényes értékek: * (összes mező), mező_neve, vagy egy tömb (array), ami a mezők neveit tartalmazza.

value string | array Maga a kereső, vagy szűrő kifejezés, ami alapján szűrni szeretnénk a találati listát. Vagy egy tömb, ami több értéket tartalmaz, ha a compare paraméter értéke IN, NOT IN vagy BETWEEN.

compare

string

A mező (field) tartalma és a szűrő kifejezés (value) összehasonlításának a módját határozza meg.
Érvényes értékek:

Érték	SQL megfelelője
=	=
!=	!=
>	>
>=	>=
<	<
<=	<=
LIKE	LIKE és a szűrő kifejezés a % jelekkel lesz kiegészítve pl.: LIKE %panzió%
NOT LIKE	NOT LIKE és a szűrő kifejezés a % jelekkel lesz kiegészítve pl.: NOT LIKE %panzió%
IN	IN - szűrő kifejezés `value` paramétere egy tömb kell hogy legyen, ami a lehetséges értékeket tartalmazza.
NOT IN	NOT IN - szűrő kifejezés `value` paramétere egy tömb kell hogy legyen, ami azokat az értékeket tartalmazza, amelyeket ki akarunk zárni a találati listából .
IS NULL	IS NULL
IS NOT NULL	IS NOT NULL
BETWEEN	BETWEEN - szűrő kifejezés `value` paramétere egy tömb kell hogy legyen, két elemmel.

Alapértelmezett érték: =

Az elérhető mezőnevekről az adott végpontot részletező fejezetben olvashatunk bővebben.

Szűrő kifejezések csoportja

filter set
típus: array
lehetséges elem típusuok: relation mint első elem, szűrő kifejezés (filter), vagy szűrő kifejezések csoportja (filter set)

Szűrő kifejezések csoportja egy tömbben megadható relációval, ahogy feljebb is leítruk. A filter set segítségével összetett kereséseket csinálhatunk, a szűrő kifejezések csoportosításával és egymásba ágyazott filter set-ekkel. Lényegében ezek a csoportok definiálják az SQL lekérdezésben a zárójeleket.

Példa:

                                    {
                                        "filter": [
                                            "AND",
                                            {
                                                "field": "title",
                                                "value": "panzió",
                                                "compare": "LIKE"
                                            },
                                            [
                                                "OR",
                                                {
                                                    "field": "created_at",
                                                    "value": "2020.10.15 18:00:00",
                                                    "compare": ">="
                                                },
                                                {
                                                    "field": "updated_at",
                                                    "value": "2020.10.15 18:00:00",
                                                    "compare": ">="
                                                }
                                            ]
                                        ]
                                    }

Nyelv

név: language
típus: string
alapértelmezett érték: hu

A language azaz nyelv paraméterrel határozhatjuk meg, hogy az adott lekérdezés találatait milyen nyelven kapjuk meg. Ha nem adunk meg ilyen paramétert akkor alapértelmezetten a magyar találatokat adja vissza. Ha az adott tábla nem tartalmaz magyar nyelvű rekordot akkor az első talált nyelv alapján keres. Kivételt képez ez alól a /media végpont ahol nem feltétlenül tartozik nyelv egy rekorhoz, így itt a nyelvvel összefüggő mezők NULL értéket is kaphatnak. A paraméter értékeként a kívánt nyelv kódját kell megadni: hu, en, de, sk

Példa:

                                    {
                                        "language": 'hu'
                                    }

Ezen kívül megadható az all érték is, így az adott rekordhoz tartozó összes nyelv szerepelni fog az API válaszában, a languages mezőben, egy tömbbe rendezve. Ilyenkor nem alkalmazható a nyelvi mezőkre az order_by és a filter paraméter.

Módosítás dátuma

név: before
típus: date string
alapértelmezett érték: null

név: after
típus: date string
alapértelmezett érték: null

A before és after paraméterek az adatszinkronizációnál jelenthetnek segítséget. Leszűkítik a találatot a megadott dátum és idő előtt, vagy után módosított rekordokra. A dátumot a következő formátumban kell megadni: Y-m-d H:i:s vagy Y-m-d

Példa:

                                    {
                                        "before": '2020-05-16 16:22:00'
                                    }

                                    {
                                        "after": '2020-03-09 08:22:00'
                                    }

Lapszámozás

név: limit
típus: number
alapértelmezett érték: 10
maximum érték: 100

név: page
típus: number
alapértelmezett érték: 1

A lapszámozással (paggination) kapcsolatos paraméterekkel tudjuk a lekérdezéseket optimalizálni. A limit paraméter határozza meg, hogy hány találatot adjon vissza egy oldalon (azaz egy lekérdezéskor) az API, a page paraméter pedig azt határozza meg hogy éppen melyik oldal találatait kérjük. Így tudjuk befolyásolni a továbbítandó adat mennyiségét. Figyelem! A limit paraméter értéke nem lehet magasabb mint 100. Ezáltal biztosítjuk, hogy a kiszolgáló ne ütközzön memória limit problémákba.

Példa:

                                    {
                                        "limit": 50,
                                        "page": 2
                                    }

Rendezés

név: order_by
típus: string
alapértelmezett érték: Általában az 'id' mező, de ez végpontonként változhat.

név: order
típus: string
alapértelmezett érték: DESC
lehetséges értékek: ASC, DESC

Az order_by paraméter határozza meg, hogy melyik mező alapján rendezzűk a találati listát és az order paraméter határozza meg hogy csökkenő vagy növekvő sorrendben kapjuk meg a találatokat.

Példa:

                                    {
                                        "order_by": 'title',
                                        "order": 'ASC'
                                    }