outlast web & mobile development - internal documentation


Outlast API guide


Ez egy általános leírás arról, hogy a web-alkalmazásainkba illesztendő API felületek milyen formátumok és elvek szerint működnek. Ha kérdés merülne fel, keress az aron@outlast.hu címen.

Request és Authentication

Bár az OAUTH2 megoldás frankó, alapvetően a legtöbb esetben -lévén hogy általában privát APIkról van szó- nekünk elég egy user és egy szép hosszú API kulcs. Ez lényegében jelszóként funkciónál és a request-el együtt kell küldeni.

A legjobb megoldás ha a user és API kulcs autentikáció a sztenderd user/pass mezőben kerül átadásra:

// CURL példa
curl -u username:password https://www.pelda.hu/api/felhasznalok.json

// URL példa
https://username:password@www.pelda.hu/api/felhasznalok.json

…így ez nem zavar be a GET vagy POST egyéb mezőibe. Ha ez nem vagy nehezen oldható meg akkor a kulcs természtesen lehet egy paraméter, pl.

https://www.pelda.hu/api/felhasznalok.json?API_KEY=password

Kérés és eredmény formátuma

Adatok olvasására a GET requestek, írására a POST requestek használata javasolt.

Egy GET request esetén általában az URLben határozzuk meg hogy melyik elemet szeretnénk lekérni. Példák:

// Az összes felhaználó lekérése
https://www.pelda.hu/api/felhasznalok.json
// Az 1234-es id-val rendelkező felhasználó lekérése
https://www.pelda.hu/api/felhasznalok/1234.json

Egy POST request esetén a request paramétereiben adjuk át, hogy milyen adatokat szeretnénk módosítani – bár nyilván ritkább esetben van szükség olyan APIra ami ezt a funkciót is támogatja.

Az eredményre legideálisabb formátum a JSON. Ezt mind PHPben (json_encode/json_decode) mind Javascript-ben (JSON.stringify/JSON.parse) egyszerűen lehet kezelni.

Eredmény adatformátumok

Javasolt, hogy az eredmények átadásakor legyen egy wrapper objektum amelynek paraméterei a kéréssel kapcsolatos általános adatokat adnak vissza. Így a visszaadott értékekből egyből kiolvasható az API verziószáma, az eredmények száma, valamint pl. lapozás és egyéb funkciók és beépíthetőek a későbbiekben.

Itt egy szép példa:

{
    "apiversion": "1.0",
    "total": 3,
    "results": [
        {
            "id": 1,
            "picture": "images/user1.png",
            "name": "Kovacs Bela"
            "registered": "1358331322",
            "friends": [
                {
                    "id": 1,
                    "name": "Hailey Timmons"
                },
                {
                    "id": 2,
                    "name": "Maya Young"
                },
                {
                    "id": 3,
                    "name": "Gabrielle Nash"
                }
            ]
        },
        [stb....]
   ]
   }

Amit érdemes kiemelni:

  • Van egy wrapper/globális objektum általános adatokkal. A tényleges adatok ennek a results tömbjében találhatóak.
  • JSON formátum ami az XMLnél egyszerűbben olvasható mind emberek, mind gépek számára.
  • Az időpont UNIX timestamp formátumban van.
  • Az egyes adat-elemekhez kapcsolódó egyéb adat-elemek (relationships) szintén jelen vannak a lekérésben egy kapcsolt tömb formájában (a példában a friends mező). Ezt nyilván akkor érdemes bennehagyni ha a kapcsolódó adat elemei viszonylag limitáltak. Ha nagyon sok kapcsolt adat van akkor ezt érdemes újabb endpointként kezelni, pl:
    https://www.pelda.hu/api/felhasznalok/1234/friends.json

Biztonság

A HTTPS használata kötelező amennyiben bármilyen nem-publikus adat kerül átadásra az API interfészen keresztül (pl. user adatok).

Ugyanez vonatkozik abban az esetben ha az API támogat POST-alapú adatmódosítást.

Az api eléréséhez szükséges jelszó egy biztonságos, generált jelszó legyen amely tartalmaz legalább 10 karaktert, számokat, valamint kis és nagybetűket.

IE8- js kompatibilitás

Ha fontos az IE8 alatti kompatibilitás akkor pluszban be kell illeszteni a json2.js fájlt ami a natív JSON funkciókat elérhetővé teszi.

<!--[if lt IE 8]>
    <script src="http://www.json.org/json2.js"></script>
<![endif]-->
Outlast Web & Mobile Development (c) 2018 | Privacy Policy |