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

Felix
Nette Core | 1161
+
+5
-

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.

Felix
Nette Core | 1161
+
+2
-

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"
}