contributte/apitte – pohodlna API knihovna (PSR-7, middlewares, openapi, examples)

před 3 lety
Felix
Nette Core | 1196
+
+4
-

contributte/apitte

Potrebujete na svem projektu vytvorit API? Pak bych vam rad ukazal knihovnu Apitte z rodiny contributte balicku.

Apitte uz je tu s nami nejaky ten patek a uz ma pres >250k stazeni. Pouziva ho cela rada firem a stal se soucasti desitek projektu.

Zakladnim stavebnim kamenem jsou tzv. controllery. Ty si muzeme predstavit jako odlehcene presentery. Ktere se soustredi jenom na prijem request a odeslani response.

Zaroven Apitte stavi na PSR-7. Jedna se o koncept (na kterem se dohodla rada PHP vyvojaru, https://www.php-fig.org/psr/psr-7/) a ten deklaruje jak vypada request a response. Zejmena jake ma metody a jak se s nim pracuje.

Dalsi skvelou feature je podpora OpenAPI specifikace. Mnozi z vas to budou znat spis pod pojmem Swagger. Jedna se o format, ktery popisuje jake endpointy se v API nachazi, co prijimaji za parametry a co naopak vraci. K jakym chybam muze dojit a jakou strukturu odpoved ma. To se velmi hodi.

Posledni takova tresnicka je podpora middlewares. Middlewary jsou zase definovane tridy, ktere muzete zapojit do stacku (middleware chain) a ty se pak dle poradi provolavaji. Muzete si je i predstavit jako takova pluginy, ktere jen do aplikaci zapojite. A tech pluginu uz existuje cela rada.

Jak takovy ukazkovy Apitte controller muze vypadat? Treba takto.

/**
 * @Path("/hello")
 */
final class HelloController implements IController
{

    /**
     * @Path("/world")
     * @Method("GET")
     */
    public function index(ApiRequest $request, ApiResponse $response): ApiResponse
    {
        return $response->writeBody('Hello world!');
    }

}
Features
composer require contributte/apitte
  • PHP 7.3+
  • Nette 3.0+
  • PSR-7 (req/res), PSR-15 (middlewares)
  • OpenAPI (generovani schema z anotaci)
  • Content negotiation (odpoved podle suffixu nebo hlavicky)
  • Spousta testu
  • …vice na Githubu ⏭
Feedback

Feedback je vitan, jeste vice jsou vitane pull-requesty.

Examples

Existuje ukazkovy projekt na Githubu i realne demo.

před 3 lety
Felix
Nette Core | 1196
+
+3
-

Apitte bylo drive rozdelene do nekolika samostatnych repozitaru (ve stejnojmenne organizaci) a Composer balicku. Byla to vize, ktera se ale ukazala jako ne uplne dobra. Vsichni totiz pouzivali Apitte jako cely stack a ne jednotlive balicky.

Proto jsem se rozhodl, ze se Apitte spoji pod jeden velky repozitar. Vycisti se od nepotrebnych veci, aktualizuje PHP atd. Bude to pro vsechny vice srozumitelne, jednoduse uchopitelne a pro me jednodussi na vyvoj.

Vse se dohodlo v ramci Contributte RFC: https://github.com/…te/issues/50

Aktualne se dokoncilo mergnuti do jednoho repozitare contributte/apitte. Poprosil bych vsechny o otestovani. Zmena by mela byt vic nez jednodussi. contributte/apitte:v0.9 odpovida poslednim verzim apitte/[balicek]:v0.8. Zadna zmena ve vasich projektech by nemela nastat.

Puvodni:

{
  "require": {
    "apitte/core": "^0.8",
    "apitte/debug": "^0.8",
    "apitte/openapi": "^0.8",
    "apitte/middlewares": "^0.8",
    "apitte/negotiation": "^0.8",
    "apitte/presenter": "^0.8",
    "apitte/console": "^0.8"
  },
  "prefer-stable": true,
  "minimum-stability": "dev"
}

Nove:

{
  "require": {
    "contributte/apitte": "^0.9"
  },
  "prefer-stable": true,
  "minimum-stability": "dev"
}
před 2 lety
ondraLE
Člen | 23
+
0
-

Mám nyní problém s instalací API pro poslední nette, nainstaluji webprojekt, updatuji composer a chci instalovat apitte:

composer require contributte/apitte

composer to zahodí, kvůli nesouladu \Nette\Utils, jsou nyní v základu na 4.0:

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires contributte/apitte v0.10 -> satisfiable by contributte/apitte[v0.10.0].
    - contributte/apitte v0.10.0 requires nette/utils ^3.2.7 -> found nette/utils[v3.2.7, v3.2.8, v3.2.9] but it conflicts with your root composer.json require (^4.0).

pokud to instaluji přes ukázky api-skeleton, sice to jde, ale je tam „abandoned Apite\Code“ a pak nefunguje PSR-7 streamy atd. pro PHP 8.2.1, jak to vyřešit. Mohu sice „natvrdo“ přepsat /vendors/guzzle, ale to není ideální řešení.
Díky za radu, případně jasný postup, jak nyní na PHP 8.2.1 postupovat při instalaci nette + apitte, staré ukázky již nefugují.

před 2 lety
Felix
Nette Core | 1196
+
0
-

Ahoj @ondraLE. Apitte jeste neni pripraveno na Nette 4, resp. nette/utils 4.0.

před 2 lety
ondraLE
Člen | 23
+
0
-

Felix napsal(a):

Ahoj @ondraLE. Apitte jeste neni pripraveno na Nette 4, resp. nette/utils 4.0.

Ok a je nějaká cesta (i např. downgrade PHP), jak používat Apitte 0.10 a nette? Zamýšlená aplikace bude mít jak GUI tak nějaké API endpointy pro externí aplikace, resp. co a v jaké verzi lze použít, aby to šlo a zaroveň nepsalo o abandoned Apitte\Core? Nebo ještě lépe, nešlo by updatovat příklady?

před 2 lety
Felix
Nette Core | 1196
+
0
-

Jasne, pouzij o trochu starsi verzi nette/utils. Verze 4.0 vysla opravdu nedavno. :-)

před rokem
tom
Člen | 171
+
0
-

Chci vytvorit API projekt ke stavajicimu eshopu. Udelam to jako oddelenou webovou aplikaci, ktera pobezi na sve adrese, napr. api.neco.cz. Nez zacnu chci se zeptat na jednu vec. Pomoci composeru si mam nejdrive nainstalovat prazdny nette projekt a do nej pak jeste apitte? Nebo mam pouzit pouze apitte a zbytek dodelat rucne? U toho API web jako takovy nebude potreba mozna max swagger. Diky za nasmerovani

před rokem
Felix
Nette Core | 1196
+
+1
-

Ahoj @tom, da se vyuzit i z predpripraveneho https://github.com/…tte-skeleton.

Zalezi co ti vyhovuje, zadna z tech cest neni spatna. Jen pak dej pozor co z composer.json realne pouzivas a co ne. Idealne at v tom mas poradek jako na plose.

před rokem
tom
Člen | 171
+
0
-

ondraLE napsal(a):

Felix napsal(a):

Ahoj @ondraLE. Apitte jeste neni pripraveno na Nette 4, resp. nette/utils 4.0.

Ok a je nějaká cesta (i např. downgrade PHP), jak používat Apitte 0.10 a nette? Zamýšlená aplikace bude mít jak GUI tak nějaké API endpointy pro externí aplikace, resp. co a v jaké verzi lze použít, aby to šlo a zaroveň nepsalo o abandoned Apitte\Core? Nebo ještě lépe, nešlo by updatovat příklady?

@ondraLE ahoj, podarilo se ti tvuj problem nejak resit? dostal jsem se ted do stejneho bodu, tak se chci zeptat, kde jsi co upravil. Diky

před rokem
ondraLE
Člen | 23
+
0
-

tom napsal(a):

ondraLE napsal(a):

Felix napsal(a):

Ahoj @ondraLE. Apitte jeste neni pripraveno na Nette 4, resp. nette/utils 4.0.

Ok a je nějaká cesta (i např. downgrade PHP), jak používat Apitte 0.10 a nette? Zamýšlená aplikace bude mít jak GUI tak nějaké API endpointy pro externí aplikace, resp. co a v jaké verzi lze použít, aby to šlo a zaroveň nepsalo o abandoned Apitte\Core? Nebo ještě lépe, nešlo by updatovat příklady?

@ondraLE ahoj, podarilo se ti tvuj problem nejak resit? dostal jsem se ted do stejneho bodu, tak se chci zeptat, kde jsi co upravil. Diky

Ahoj, nakonec jsem to přepsal natvrdo, teď jsem nekoukal, jestli už vyšla nová verze nette/utils. Další apku, která potřebuje GUI i API jsem nakonec dělal klasicky přes controllery, jen s tím, že mám nějaký BASEController pro GUI a BASEController pro API, který mi tam nastrká více parametrů. Apitte a nové Nette jsem nerozchodil. :(