API elérése és authentikáció

API elérése

Az API végpont a https://cloudapi.conycms.com domain alatt érhető el. A végpont bármilyen HTTP klienssel hívható, amivel megvalósítható a jelen dokumentumban leírt kommunikáció.

Kommunikáció formátuma

A ConyCMS API szabványos REST API hívásokkal érhető el, ennek megfelelően a különböző célú végpontokat különböző HTTP metódusokkal lehet hívni. Bizonyos esetekben ugyanazt a végpontot több metódussal is hívhatjuk, ebben az esetben a metódus határozza meg az elvárt működést. Ilyen például egy konkrét bejegyzés

• megnyitása
• módosítása
• törlése mely esetben ugyanazt a végpontot kell hívni különböző HTTP metódusokkal.

Az API végpontok JSON formátumban kommunikálnak.

A következő típusú értékeket a következő formátumban küldi és várja az API:

• datetime
  • string
  • formátum: W3C (YYYY-MM-DDTHH:MM:SSP, például: 2000-01-01T00:00:00+00:00)
• bool
  • number
  • 0: false
  • 1: true
  • bármilyen egyéb, nem 0 érték: true (ilyen értéket nem küld, de ha fogad, akkor tudja értelmezni)

Figyelem: a dokumentációkban szereplő mezők mellett bármikor megjelenhetnek további, még nem dokumentált mezők, illetve az opcionálisnak jelölt mezőknél előfordulhat üres érték, és a mező teljes hiánya is!

HTTP GET

A GET metódusú hívásokkal lehet adatokat lekérni. Ezek a hívások egy konkrét elemet, vagy több elem listáját adják vissza.

HTTP POST

A POST metódusú hívásokkal lehet új bejegyzést létrehozni. Egy ilyen hívás egyszerre egy bejegyzést hoz létre.

HTTP PATCH

A PATCH metódusú hívásokkal lehet egy létező bejegyzést módosítani.

HTTP DELETE

A DELETE metódusú hívásokkal lehet egy létező bejegyzést törölni. A ConyCMS verziókezelő funkciója miatt csak bizonyos adatokat lehet véglegesen törölni, ahol státusz állítással lehet töröltnek jelölni egy bejegyzést, az az eset módosításnak számít.

Visszatérési érték

Az API végpontok a HTTP kérésre adott HTTP státusszal, és a visszaadott JSON formátumú adattal jelzik, hogy az adott hívásnak mi lett az eredménye.

A végpontok által visszaadott adat pontos tartalma az adott végpont dokumentációjában található. A következő HTTP státusz kódok fordulhatnak elő a hívások során:

HTTP 200

A hívás sikeres volt. Amennyiben másképp nincs meghatározva, a hívások ezzel a státusszal térnek vissza. Bizonyos hívások hiba esetén is ezzel a státusszal térnek vissza, ekkor a visszaadott adatban részletezik, hogy mi volt a probléma.

HTTP 201

A hívás sikeres volt, létre lett hozva egy új bejegyzés. Egyes POST metódusú hívások ezzel a státusszal térnek vissza, ha sikeresen létrehoztak egy új bejegyzést.

HTTP 204

A hívás sikeres volt, nem kell adatot visszaadni. Egyes DELETE metódusú hívások ezzel a státusszal térnek vissza, ha sikeresen töröltek egy új bejegyzést. Ennél a státusznál mindig üres a response body.

HTTP 401

Authentikációs probléma. Az adott végpont használatához authentikálni kell a felhasználót, de ez nem sikerült. Ennek a főbb okai: nem lett megadva az authentikációs token hibás a token formátuma hibás vagy korrupt a token tartalma lejárt a token

HTTP 403

Jogosultsági probléma. A felhasználónak nincs joga az adott végponthoz, vagy az adott végpont által kezelt bejegyzéshez.

HTTP 404

Az adott API végpont nem létezik, vagy nem hívható az adott HTTP metódussal.

HTTP 409

Általános probléma a beküldött adatokkal. Általában POST, illetve PATCH metódusú hívásoknál fordul elő, amennyiben a beküldött adattal valamilyen probléma van.

HTTP 410

A bejegyzés nem található.

HTTP 500

Rendszer hiba.

CORS

Az összes API végpont hívható OPTIONS HTTP metódussal, ezek a hívások minden esetben HTTP 200 státusszal térnek vissza (akkor is, ha az adott végpont nem létezik), és a válasz fejlécei között szerepelnek a CORS bejegyzések:

Emiatt közvetlenül böngészőből, JavaScript segítségével AJAX hívásokat is lehet indítani az API felé.

Fontos, hogy az Access-Control-Allow-Methods értéke minden esetben ugyanaz, így nem használható annak lekérésére, hogy valójában milyen HTTP metódusokkal lehet az adott végpontot hívni.

Authentikáció

Az API végpontok használata authentikációhoz kötött, ez alól csak azok a kivételek, ahol ez kifejezetten jelezve van a dokumentációban.

Az authentikációhoz a HTTP kérés fejlécei között az Authorization header-ben kell egy Bearer tokent küldeni.

Az authentikációs tokent a login végponton lehet lekérni, egy meglévő tokent pedig az aktuális user lekérésével lehet tesztelni.

Login

POST /user/login
{
    "username": "user@example.com",
    "password": "MyT0pSecretPassw0rd"
}

A sikeres belépés esetén a következő választ adja a végpont:

{
    "authToken": "very_long_authorization_token_string"
}

PHP példa kód:

<?php

$curl = curl_init();

curl_setopt_array(
    $curl,
    array(
        CURLOPT_URL => 'https://cloudapi.conycms.com/user/login',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_POSTFIELDS =>'{"username": "user@example.com","password": "MyT0pSecretPassw0rd"}',
        CURLOPT_HTTPHEADER => array(
            'Content-Type: application/json'
        ),
    )
);

$response = curl_exec($curl);

$headerSize = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
$httpStatus = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$responseBody = substr($response, $headerSize);
$responseObject = json_decode($responseBody, true);

$authToken = isset($responseObject['authToken']) ? $responseObject['authToken'] : null;

Aktuális user lekérés

Ennél a végpontnál már küldeni kell a kérés fejlécei között az authentikációs tokent.

GET /user/current

Amennyiben érvényes a token, a következő választ adja a végpont:

{
    "username": "user@example.com"
}

PHP példa kód:

<?php

$curl = curl_init();

curl_setopt_array(
    $curl,
    array(
        CURLOPT_URL => 'https://cloudapi.conycms.com/user/current',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'GET',
        CURLOPT_HTTPHEADER => array(
            'Authorization: Bearer very_long_authorization_token_string'
        ),
    )
);

$response = curl_exec($curl);

$headerSize = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
$httpStatus = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$responseBody = substr($response, $headerSize);
$responseObject = json_decode($responseBody, true);

$userName = isset($responseObject['username']) ? $responseObject['username'] : null;