Serveis web amb Laravel

De Cacauet Wiki
Dreceres ràpides: navegació, cerca

Per poder seguir amb normalitat aquest article cal haver llegit i treballat Laravel.


Introducció[modifica]

Articles previs:

Articles següents:

Perquè Laravel per a serveis web?[modifica]

No és imprescindible utilitzar Laravel per implementar un servei web. Ens és convenient pels següents motius:

  1. En el curs de M7 de DAW estem treballant amb aquest framework i ens interessa aprofundir el seu coneixement.
  2. Integrarem la part del frontend de la nostra web juntament amb la API que farem.
  3. Laravel facilita l'accés a la base de dades a través del ORM Eloquent, que resulta molt útil.


L'exemple laravel-karaoke[modifica]

L'exemple que us mostrem és una web per confeccionar llistes de temes de karaoke per les nostres festes i demanar tanda. Es poden crear llistes i afegir temes en cadascuna, amb el corresponent vídeo del YouTube perquè puguem posar-ho en marxa fàcilment.

https://github.com/emieza/laravel-karaoke

Podeu fer un cop d'ull al software funcionant en un servidor de test a (OJU, el httpS és important, la versió http és diferent):

https://jolgorio.tk/


Primera prova de la API[modifica]

Anem a implementar una primera prova de API en un projecte Laravel nou. Si et cal, crea'n un.

Totes les funcions que vulguem implementar per al nostre sistema hem de començar per indicar-les al arxiu de rutes:

routes/api.php

De fet, les podríem implementar al mateix arxiu. Quan es compliquin, però, convindrà crear un controlador com vam fer al tutorial de Laravel.

Afegiu el següent codi a routes/api.php:

Route::get('/ping', function(Request $request) {
    return "pong! :)";
});

Poseu en marxa el servidor i proveu la funció amb:

$ curl localhost:8000/api/ping
pong! :)[email protected]:~/dev/laraveltest1$ 

Noteu que:

  • Encara que hem definit la ruta "/ping", per poder-la cridar hem de fer "/api/ping". Ve predefinit pel Laravel, tot i que no té perquè ser així.
  • Ens contesta el què hem posat al RETURN final
  • No retorna HTML, retorna un text que pot ser qualsevol cosa
  • No hi ha \n final (s'enganxa amb el prompt de la shell)

Headers en la crida curl[modifica]

Per veure els headers de retorn, podem utilitzar "-i", pot ser molt útil per depurar:

$ curl -i localhost:8000/api/ping

Obtindrem:

HTTP/1.1 200 OK
Host: localhost:8000
Connection: close
X-Powered-By: PHP/7.0.15-0ubuntu0.16.04.4
Cache-Control: no-cache
Content-Type: text/html; charset=UTF-8
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
Date: Thu, 09 Mar 2017 17:25:32 GMT 
pong! :)[email protected]:~/dev/laraveltest1$ 


Exemples de API: laravel-karaoke[modifica]

En el projecte karaoke en Laravel, el podeu veure aquí:

Recordem que per crear un controller amb Laravel ho fem amb (per exemple):

$ php artisan make:controller ApiController

Si mireu TemaController pareu atenció que per poder fer crides com TemaController::fet($id) , necessitem que siguin funcions estàtiques (static).

Ara, per poder mirar el nº de vots, a routes/api.php tindrem:

Route::get('/nvots/{id}', function(Request $request, $id) {
    return TemaController::nvots( $id );
});


Especificacions d'una API[modifica]

És molt important especificar adequadament una API per tal que la pugui fer servir molta gent.

En l'exemple del karaoke tenim 3 crides, i les especificacions les indiquem amb quadres com els que mostrem a continuació:

  • /api/nvots/{tema_id}
  • /api/vota/{tema_id}
  • /api/fet/{tema_id}


nvots[modifica]

Al ser una crida GET, els paràmetres han d'anar a la URL. Si fos POST, anirien afegits en el cos de la request:

Veure codi del [email protected]

Request
GET /api/nvots/{tema_id}
Param Values Description
tema_id integer ID del tema del que volem saber el nº de vots que té

Aquesta response retorna les dades en format JSON, però podria tenir altres formats (XML, plain text):

Response : JSON
GET /api/nvots/{tema_id}
Param Values Description
status "OK" / "ERROR" Estat intern de la consulta/acció
nvots integer Total de vots per al tema
tema_id integer ID del tema consultat

Per exemple, per testejar-la:

$ curl http://localhost:8000/api/nvots/1
{"status":"OK","tema_id":"1","nvots":1}

Per testejar l'exemple en producció, podeu provar (el -k és important perquè no demani els certificats HTTPS):

$ curl https://jolgorio.tk/api/nvots/1 -k
{"status":"OK","tema_id":"1","nvots":2}


vota[modifica]

Veure codi de [email protected]

Request
GET /api/vota/{tema_id}
Param Values Description
tema_id integer ID del tema del que volem saber el nº de vots que té
Response : JSON
GET /api/vota/{tema_id}
Param Values Description
status "OK" / "ERROR" Estat intern de la consulta/acció
vot true / false Estat actual del nostre vot de la nostra IP
nvots integer Total de vots per al tema
message text Missatge de text amb la descripció de l'error o acció


fet[modifica]

Veure codi de [email protected]

Request
GET /api/vota/{tema_id}
Param Values Description
tema_id integer ID del tema del que volem saber el nº de vots que té
Response : JSON
GET /api/vota/{tema_id}
Param Values Description
status "OK" / "ERROR" Estat intern de la consulta/acció
fet true / false Estat actual del tema (fet / no fet)
message text Missatge de text amb la descripció de l'error o acció