Používáte Nette pro RESTful API?

Tak určitě je toho víc, co stojí za zmínku. :P Například:

– ublaboo/api-router (http://ublaboo.org/api-router/)
 – ublaboo/api-docu (http://ublaboo.org/api-docu/)

Jsem fakt smutnej, že se to v tvém příspěvku neobjevilo, jakto? Kde o tom chybí zmínka?

Jedou mi tyhle knihovny na pár menších a pár velkých projektech. A jedou.

Co se týče autorizace, nerad cpu věci s tím související do takových knihoven. A navíc je to na pár řádek kódu. Autorizace přes token se prdne do BasePresenteru a basta. S routováním a pod to nemá nic společného.

V čem tyto apíčkové ublaboo knihovny excelují je jedno – dokumentace (jedna routa, celé api). Doporučuju prostudovat web – je taky jenom pár řádek textu.

Taky by mě docela zajímalo, jestli někdo automaticky mapuje rest api na entity db. Určitě ne POST, ale GET by mohl být zajímavý a přinést užitek spolu s úsporou času!

Verzování api snad není moc „řešitelné“… – To by mě zajímalo, co tím autor myslel?

Editoval Pavel Janda (27. 5. 2016 17:10)

Pavel Janda napsal(a):

– ublaboo/api-docu (http://ublaboo.org/api-docu/)

Jak tak koukám na API Docu: Je to hezký nápad, jen by to ještě šlo vylepšit o automatické generování té dokumentace z Doctrine entit například. Takhle musí vývojář při změně upravit entitu a zároveň endpoint + jeho dokumentaci. Nebylo by fajn tohle moct upravovat jen na jednom místě? :)

Editoval Filip Klimeš (27. 5. 2016 17:19)

Pavel Janda napsal(a):

@FilipKlimeš To se děje na jednom místě. Vše máš v anotaci presenteru/akce. Jak definici routy, tak description.

Rozumím, spíš jsem tím myslel tu integraci s ORM. Z mé zkušenosti podoba endpointů často kopíruje právě podobu ORM entit. Navíc jeden endpoint často odpovídá jedné entitě. (Možná se pletu, tak mě kdyžtak vyveďte z omylu)

A myslím, že POST ne, protože skoro pořád potřebuješ dělat víc věcí najednou. Jednou poslat obrázek na AWS, jednou pushnout notifikaci, jednou poslat sms a jindy pustit vodotrysk. A tohle všechno hnát přes entitu .. to by se mi nelíbilo.

Na druhou stranu – pokud bys dokázal nějak pěkně implementovat ty filtry, mohla by tomu pomoci právě kombinace filtrů, eventů a pod.

Přesně tak, tyhle věci by šlo podle mě hezky řešit filtry :). Popřípadě pouštět eventy, např. při vytvoření nové entity, updatu atp.

Editoval Filip Klimeš (27. 5. 2016 17:31)

@kleinpetr
1, Přesně tak, api-router (doporučuji začít stavět na ořezaném web-projectu: composer create-project ublaboo/api-router-project) je pouze router. Mně se nelíbí postup, kdy routovací vrstva řeší přihlášení a podobné věci.

2, Autorizace se dá řešit na spoustě míst a různým způsobem (v závislosti na typu aplikace). Nejčastěji bych asi vytvořil AbstractController imlpementující IPresenter (to je snad jen metoda ::run(Application\Request $request): Application\IResponse) a potom kontroloval hlavičky hned za začátku této metody (případně v nějakém middlewaru – odbočka k zajímavé knihovně z balíčku namespacu contrubutte). Například aplikací definované tokeny.
Nebo může jít o SPA/PWA/blabla prostě aplikaci v JS, která se jednou přihlásí k backendu a už jede přihlášená. Ta by poslala poprvé třeba username/password a o víc by se nestarala, jelikož moje aplikace by uživatele normálně přihlásila pomocí Nette\Security\User a v dalších requestech by byl uživatel automaticky přihlášen (bacha, httpOnly cookiny).

Tohle téma by vyneslo na samotnou přednášku. Kdybys měl konkrétnější dotaz, tak se ptej. :)

@kleinpetr Zeleží na tom – kdo bude k tvému api přistupovat. JavaScript? Jiný backend? Mobilní aplikace?

@kleinpetr Pak bych klidně využil nativní http autorizaci, případně vlastní http hlavičku a autorizační token, který budou obě aplikace sdílet (např v proměnné prostředí nebo ve vendoru [radši tu proměnnou prostředí]).

Client appka vytvoří request s http auth, tvoje appka se v každém requestu od clienta koukne na http auth hlavičku, ověří a jede dál (případně request zamítne při nevalidní autorizaci).

@kleinpetr No, v action metodě by ses zbytečně opakoval.. Spíš si to prdni někam do předka, který to bude kontrolovat pro všechny akce společně. A teprv po kontrole autorizace se to rozstřelí do actionMetod.

Proměnnou prostředí jsem myslel toto: Já nerad dávat různé konfigurační parametry přímo do gitu projektu. Je to tam zbytečně na očích. Jsou to parametry typu: přístupy do databáze, různé tokeny apíček, přístupy do redisu, hesla k smtp schránkám a podobně. Dávám je pak do ENV vars, kam může šahat vždy jen master projektu. Ale je to samozřejme zbytečné, pokud děláš na appce sám. To je vhodné řešení například pro tuny aplikací startovaných z docker-compose.

@kleinpetr
1, Smazal jsi cache?
2, Mrkni na Postmana (https://www.getpostman.com/) – žůžo klient pro testování apíček
3, ErrorController klidně vynech. Nechá se na něj třeba přesměrovat, ale být tam asi nemusí (asi ?)
4, Nenačítá
5, Jestli budeš přihlašovat pokaždé jiného uživatele, tak normálně volej login a ano, udělej si nějaký authToken, který vrátíš client apíčku v odpovědi – tento token bude muset client apíčko při každém dalším requestu vracet.
Pokud se nebudou přihlašovat uživatelé, ale prostě jedno apíčko, stačí kontrola token == token..
Session bych do toho asi netahal.

Editoval Pavel Janda (31. 8. 2017 22:04)

@kleinpetr config.platform.php – to nevím, co je.

Rozdíl je v tom, že UI\Presenter ti řeší templating, kanonizaci url, signály, action/beforeRender/render/… Prostě tunu věcí, které API vůbec nemá co řešit. Pro lepší pochopení – mrkni se na UI\Presenter::run() :)

@kleinpetr V $request->getParameter('action') by ti teoreticky mohla přijít action..

Ideálně? :D Udělej si na to třeba v1 modul? Bůhví, těch způsobů je zase vícero. Modul podle verze je asi nejsnazší a nejrychlejší způsob.

@PavelJanda
Tak jsem to nakonec nějak rozběhl na klasickém nette projektu.
Nicméně mám pár dotazů ohledně apiDocu

když zadám toto, přesně podle tvé dokumentace

/**
 * API Users
 *
 * @ApiRoute(
 *     "/api/v1/users[/<id>]",
 *     format="json",
 *     presenter="V1:Users",
 *     section="Users",
 *     priority=1
 * )
 */
class UsersPresenter extends BasePresenter
{

    /**
     * Get user detail
     *
     * @ApiRoute(
     *    "/api/v1/users/<id>",
     *    method="GET",
     *    example={
     *      "id": 110,
     *      "name": "John",
     *      "surname": "Doe",
     *      "email": "john@doe.cz",
     *      "createdDate": "2017-09-03 13:12:08",
     *    },
     *    tags={
     *        "secured": "#e74c3c"
     *    },
     *    response_codes={
     *    200="Success",
     *    400="Error in authentication process",
     *    401="Invalid authentication"
     *  }
     * )
     */
    public function actionRead($id)
    {
        if ($id) {
            $this->sendJson($this->apiResponseFormatter->formatMessage($id));
        }

        $this->sendJson($this->apiResponseFormatter->formatMessage('list'));
    }

    /**
     * Create user
     *
     * @ApiRoute(
     *    "/api/v1/users",
     *    method="POST",
     *    example={
     *      "id": 110,
     *      "name": "John",
     *      "surname": "Doe",
     *      "email": "john@doe.cz",
     *      "createdDate": "2017-09-03 13:12:08",
     *    },
     *    parameters={
     *     "email"={"type": "string"},
     *     "name"={"type": "string"},
     *     "surname"={"type": "string"}
     *    },
     *    tags={
     *        "secured": "#e74c3c"
     *    },
     *    response_codes={
     *    200="Success",
     *    400="Error in authentication process",
     *    401="Invalid authentication"
     *  }
     * )
     */
    public function actionCreate()
    {

    }

}

1. když zadám pouze /api/v1/users – tak mi vyhodí no-route (když uzavřu <id> do []) tak mi docu ukáže dokumentaci jakobych měl zadané ID, což je špatně.
2. Jak mohu přidat parametry pro POST, které chci zobrazit v dokumentaci ? když je přidám přes parameters, tak mi hodí, že je nemám uvedené v masce, což je jasný, protože je chci dostat POSTEM.
3. Jak docílit toho, že když si zobrazím dokumentaci čistě pro GET api/v1/users (až bude fungovat) aby se mi zobrazilo, že jsou dostupné metody POST,PUT,DELETE atp, případně proklik na dokumentaci s parametrem apiRouteMethod
4. Jak mohu nastavit dokumentaci pro GET api/v1/users (až bude funkční), tak jako ostatní metody, např. example apod ?

Díky moc :)

Editoval kleinpetr (1. 9. 2017 23:59)

Ok, přijde mi to jako takové nepropracované do detailu, asi použiju apiary.io. Jinak routování se zdá, že funguje jak má.

Mockrát díky za pomoc, muselo to být vyčerpávající.

Petr