API con Laravel

Algunos enlaces interesantes:

• Tutorial Creación de un API RESTful

• Códigos de error

• Buenas prácticas para el diseño de una API

  ¿Qué es un Servicio Web?

• De acuerdo a Wikipedia:

Un servicio web (en inglés, web service o web services) es una tecnología que utiliza un conjunto de protocolos y estándares que sirven para intercambiar datos entre aplicaciones.

• Se trata de que una aplicación web intercambie información con otra aplicación mediante el protocolo HTTP.

• Durante bastante tiempo se usó XML y el estándar SOAP para esta finalidad.

• Actualmente se usa JSON y el estándar de facto API REST

¿Qué es JSON?

• JavaScript Object Notation

• Es una sintáxis creada para codificar objetos en JavaScript

• Su uso se ha extendido mucho como alternativa a XML por lo que se considera un formato independiente de dicho lenguaje.

¿Qué es un API?

• Application Programming Interface, Interfaz de Programación de Aplicaciones.

• Es decir una interfaz que permite crear aplicaciones que usan determinado recurso.

• Una API web usar el protocolo HTTP para lograr dicho objetivo.

¿Qué es un API REST?

• Es una API web que sigue determinado stándar de facto.

• El intercambio de información se basa en el uso de HTTP.

• Usa un protocolo cliente-servidor sin estado. No pueden usarse cookies para mantener el estado de la sesión.

• Cacheable. Una respuesta puede definirse como cacheable para evitar peticiones recurrentes.

• Hipermedia como motor del estado. A partir de una dirección principal pueden obtenerse enlaces a todos los recursos del servicio.

• Se define un conjunto de operaciones: GET, POST, PUT, DELETE.

• Las operaciones CRUD se pueden asimilar al anterior conjunto y a unas rutas determinadas:

Ruta	Verbo	Descripción
/studies	GET	Obtenemos todos los estudios
/studies	POST	Creamos un estudio
/studies/{id}	GET	Obtenemos un estudio
/studies/{id}	PUT	Modificamos un estudio
/studies/{id}	PATCH	Modificación parcial
/studies/{id}	DELETE	Borramos un estudio

Se pueden añadir otras rutas para complementar el acceso:

• Podemos definir búsquedas por un campo:

  GET /studies?code=IFC303

• Podemos definir búsquedas más complejas:

  GET /studies/search?family=IFC&level=GS

• Podemos definir ordenaciones, en este caso descendente:

  GET /studies?sort=-updated_at

Y podemos reflejar las relaciones:

//Lista de módulos de un estudio
GET /studies/1/modules 
//Busqueda de un módulo dentro de un estudio
GET /studies/1/modules/3
//Creación de un módulo dentro de un estudio
POST /studies/1/modules
//Modificación de un módulo dentro de un estudio
PUT /studies/1/modules/3
//Borrado de un módulo dentro de un estudio
DELETE /studies/1/modules/3

Postman

• Utilizaremos Postman para testear nuestra API

  • Independiente de que hagamos tests por otro lado

• Es una herramienta muy extendida

Comprobación API inicial

• Vamos a crear una ruta inicial:

Route::get('/', function() {
    return "Bienvenido a la API Laravel 20";
});

• Abre Postman y prueba su funcionamiento.

• El anterior ejemplo funciona pero es más correcto de la siguiente manera:

  • Definimos el código de estado Http

  • Los arrays ordenados se covierten en arrays JSON

  • Los arrays asociativos se convierten en objetos

  • Los objetos se convierten en objetos:

//usar la función response() y el método json para cambiar el status
//el $data que enviamos podría ser cualqueir cosa: objeto, array,...
Route::get('/', function() {
  $data = ['message' => 'Bienvenido a la API'];
  return response()->json($data, 200);
});

Códigos de estado:

• 200's usados para respuestas con éxito.

• 300's usados para redirecciones.

• 400's usados cuando hay algún problema con la petición.

• 500's usados cuando hay algún problema con el servidor.

• Lista de códigos HTTP que se deberían utilizar en la API RESTful:

  • 200 OK - Respuesta a un exitoso GET, PUT, PATCH o DELETE. Puede ser usado también para un POST que no resulta en una creación.

  • 201 Created – [Creada] Respuesta a un POST que resulta en una creación. Debería ser combinado con un encabezado Location, apuntando a la ubicación del nuevo recurso.

  • 204 No Content – [Sin Contenido] Respuesta a una petición exitosa que no devuelve un body (por ejemplo en una petición DELETE)

• 304 Not Modified – [No Modificada] Usado cuando el cacheo de encabezados HTTP está activo y el cliente puede usar datos cacheados.

• 400 Bad Request – [Petición Errónea] La petición está malformada, como por ejemplo, si el contenido no fue bien parseado. El error se debe mostrar también en el JSON de respuesta.

• 401 Unauthorized – [Desautorizada] No se ha podido autenticar al usuario. Sin credenciales o credenciales no válidas.

• 403 Forbidden – [Prohibida] Cuando la autenticación es exitosa pero el usuario no tiene permiso al recurso en cuestión.

• 404 Not Found – [No encontrada] Cuando un recurso se solicita un recurso no existente.

• 405 Method Not Allowed – [Método no permitido] Cuando un método HTTP que está siendo pedido no está permitido para el usuario autenticado.

• 409 Conflict - [Conflicto] Cuando hay algún conflicto al procesar una petición, por ejemplo en PATCH, POST o DELETE.

• 410 Gone – [Retirado] Indica que el recurso en ese endpoint ya no está disponible. Útil como una respuesta en blanco para viejas versiones de la API

• 415 Unsupported Media Type – [Tipo de contenido no soportado] Si el tipo de contenido que solicita la petición es incorrecto

• 422 Unprocessable Entity – [Entidad improcesable] Utilizada para errores de validación, o cuando por ejemplo faltan campos en una petición.

• 429 Too Many Requests – [Demasiadas peticiones] Cuando una petición es rechazada debido a la tasa límite .

• 500 – Internal Server Error – [Error Interno del servidor] Los desarrolladores de API NO deberían usar este código. En su lugar se debería loguear el fallo y no devolver respuesta.

CRUD de Estudios en API

• Antes de empezar, prueba otras rutas y fuerza la página de error "No encontrado".

• Obtenemos un error 404 html.

• Mejor un error 404 limpio en JSON.

• Debemos definir una ruta de fallback, o ruta por defecto si ninguna otra es la solicitada

Route::fallback(function () {
  return response()->json(['error' => 'No encontrado'], 404);
});

Controlador y rutas

• Vamos a necesitar un controlador para gestionar nuestro recurso.

• Ojo, vamos separar los controladores API del resto:

php artisan make:controller Api/StudyController

• Basta con incluir una ruta resource y añadir el modificador except:

Route::resource('studies', StudyController::class)->except([
    'create', 'edit'
]);

Index

public function index()
{
  return Study::all();  
  //No es lo más correcto porque se devolverían todos los registros. Se recomienda usar Filtros o paginación.
}

// Se debería devolver un objeto con una propiedad como mínimo data y el array de resultados en esa propiedad.
// A su vez también es necesario devolver el código HTTP de la respuesta.
public function index()
{
    // return Study::all();
    $studies = Study::all();

    return response()->json(['status' => 'ok', 'data' => $studies], 200);
}

Show

public function show($id)
{
  // Corresponde con la ruta /studies/{study}
  // Buscamos un study por el ID.
  $study=Study::find($id);

  // Chequeamos si encontró o no el study
  if (! $study)
  {
    // Se devuelve un array errors con los errores detectados y código 404
    return response()->json(['errors'=>(['code'=>404,'message'=>'No se encuentra un studio con ese código.'])],404);
  }

  // Devolvemos la información encontrada.
  return response()->json(['status'=>'ok','data'=>$study],200);
}

Create

    public function store(Request $request)
    {
        $validator = Validator::make($request->all(), [
            'code' => 'required|unique:studies,code|max:6',
            'name' => 'required',
            'abreviation' => 'required',
        ]);

        if ($validator->fails()) {
            return response()->json(['errors' => $validator->errors()], 422);            
        }

        $new = Study::create($request->all());
        return response()->json($new, 201);
    }

Update: PUT

public function update(Request $request, $id)
{
    $study = Study::find($id);
    //si no se encuentra 404
    if (!$study) {
        return response()->json([
            'status' => 404,
            'message' => 'No se ha encontrado un estudio con ese código'
        ], 404);
    }
    //si no valida 422
    $validator = Validator::make($request->all(), [
        'code' => 'required|unique:studies,code|max:6',
        'name' => 'required',
        'abreviation' => 'required',
    ]);

    if ($validator->fails()) {
        return response()->json(['errors' => $validator->errors()], 422);            
    }

    //todo ok 201
    $study->fill($request->all());
    $study->save();
    return response()->json([
        'status' => 'ok',
        'data' => $study
    ], 200);
}

Delete

• Estamos repitiendo la comprobación de 404 una y otra vez.

• Sería interesante crear un método para no repetir código de esta manera.

//DRY. Don't Repeat Yourself
public function check404($study)
{
    if (!$study) {
        response()->json([
            'status' => 404,
            'message' => 'No se ha encontrado un estudio con ese id'
        ], 404)->send();
        die();
    }
}

public function destroy($id)
{
    $study = Study::find($id);
    $this->check404($study);

    try {
        //status 204: No content
        $study->delete();
        return response()->json([
            'Sin contenido'
        ], 204);
    } catch (\Throwable $th) {
        return response()->json([
            'status' => 'error',
            'message' => 'Borrado fallido',
            'error_message' => $th->getMessage()
        ], 409);
    }
}

Autenticación: JWT

• REST se define como sin estado. Esto implica la no utilización de cookies y por ende sesiones.

• JSON Web Token es un estándar usado para este fin.

• Cuando un usuario hace login recibe un token que debe guardar en su aplicación cliente.

• En el resto de peticiones debe entregar ese token para ser identificado.

• Para JWT vamos a usar la librería tymondesigns/jwt-auth
• Veamos como usarla para:

  • Hacer login

  • Hacer logout

  • Registrar un usuario

  • ...

Instalación

• Instalar dependencias:

composer require tymon/jwt-auth

• Tomar fichero de configuración y crear clave de cifrado

php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"
php artisan jwt:secret

• La clave de cifrado se guarda en .env. Deberemos repetirlo en cada instalación.

• Debemos modificar el fichero config/auth.php. Apartado guards

  'api' => [
      'driver' => 'jwt',
      'provider' => 'users'   
  ],

Modificar el modelo User

• Añadimos un "use" en la cabecera

use Tymon\JWTAuth\Contracts\JWTSubject;

• Más abajo en la definición de clase, implements ...

class User extends Authenticatable implements JWTSubject

• Por último, añadimos estos métodos:

    /**
    * Get the identifier that will be stored in the subject claim of the JWT.
    *
    * @return mixed
    */
    public function getJWTIdentifier()
    {
        return $this->getKey();
    }
    /**
    * Return a key value array, containing any custom claims to be added to the JWT.
    *
    * @return array
    */
    public function getJWTCustomClaims()
    {
        return [];
    }

Rutas y controlador

• Usaremos un controlador. Lo creamos:

php artisan make:controller Api/AuthController

• Necesitamos unas rutas en api.php para los métodos de autenticación:

//En la parte superiror:
use App\Http\Controllers\Api\AuthController;

// rutas con este prefijo: /api/auth/....
Route::group([
    'middleware' => 'api',
    'prefix' => 'auth'
    ], function ($router) {
        Route::post('register', [AuthController::class, 'register']);
        Route::post('login', [AuthController::class, 'login']);
        Route::post('logout', [AuthController::class, 'logout']);
        Route::post('refresh',  [AuthController::class, 'refresh']);
        Route::post('me',  [AuthController::class, 'me']);
});

Métodos del controlador

• Necesitamos añadir algunos "use":

use JWTAuth;
use Auth;
use App\Models\User;
use Illuminate\Support\Facades\Validator;
use Tymon\JWTAuth\Exceptions\JWTException;

• DRY. Para enviar el token al cliente usaremos este método:

protected function respondWithToken($token, $status=200)
{        
    return response()->json([
        'access_token' => $token,
        'token_type' => 'bearer',
        'expires_in' => auth('api')->factory()->getTTL() * 60
    ], $status);
}

• Veamos ahora los métodos:

• El constructor con un middleware.

  public function __construct()
  {
      $this->middleware('auth:api', ['except' => ['login', 'register']]);
  }

• Register

  public function register(Request $request)
  {
      $validator = Validator::make($request->all(), [
          'name' => 'required|string|max:255',
          'email' => 'required|string|email|max:255|unique:users',
          'password' => 'required|string|min:6|confirmed',
      ]);
  
      if($validator->fails()){
          return response()->json($validator->errors(), 400);
      };
  
      $user = User::create([
          'name' => $request->name,
          'email' => $request->email,
          'password' => bcrypt($request->password),
      ]);
  
      $token = JWTAuth::fromUser($user);
      return response()->json(compact('user','token'), 201);
  }

• Login

  public function login(Request $request)
  {        
      $credentials = $request->only('email', 'password');
      try {
          if ($token = JWTAuth::attempt($credentials)) {
              return $this->respondWithToken($token); //OK
          } else {
              return response()->json(['error' => 'Credenciales inválidas'], 400);                
          }
      } catch (JWTException $e) {
            \Log::error($e->getMessage());
          return response()->json(['error' => 'No se pudo crear el token'], 500);
      }
  }

• Logout

  public function logout()
  {
      // auth()->logout();
      Auth::logout();
  
      return response()->json(['message' => 'Salió con éxito']);
  }

• La información del usuario: me().

  public function me()
  {
      return response()->json(Auth::user());
  }

• Refresh

  public function refresh()
  {
      return $this->respondWithToken(JWTAuth::refresh(JWTAuth::getToken()));
  }

Autorización

• Autenticar es identificar al usuario:

  • En web usamos sesión y los controladores que nos brinda Laravel

  • En api acabamos de crear el controalador Api/AuthController

• El middleware Auth nos permite limitar el acceso a una ruta a usuarios identificados.

• Pero no nos permite un control de acceso más elaborado

• Laravel ofrece varias soluciones para esto. Vamos a estudiar las políticas.

• Una política es una clase guardada den app/Policies

• Una política va siempre asociada a un modelo.

• Su creación:

php artisan make:policy StudyPolicy --model=Study

Registro

• Una vez creada debemos registrarla en el array $policies en AuthServiceProvider

    protected $policies = [
        'App\Study' => 'App\Policies\StudyPolicy',
    ]

• Si no hacemos esto siempre obtendremos un estado 403 No autorizado

Definir reglas

• Cada tipo de acceso se asocia a una regla. Una regla será un método dentro de la política.

• Por defecto las polítcas traen una colección de reglas/métodos.

• Por ejemplo el método update lo podemos usar para actualizar un estudio. Sus argumentos deben ser el user y un objeto del modelo protegido (Study):

public function update(User $user, Study $study)
{
    return $user->id === $study->user_id;
}

• Otros métodos se asocian a la clase en vez de a un objeto (create, viewAny, ...). Observa, crear o ver todos los estudios hace referencia a la clase, no a un estudio concreto.

public function create(User $user)
{
    return $user->isAdmin();
}

Autorización web.

• Para autorizar basta con usar el método autorize() del controlador:

• Ejemplo sobre una regla de clase:

public function create()
{
    $this->authorize('create', Study::class);
    return view('study.create');
}

• Ejemplo sobre una regla de objeto

    public function update(Request $request, Study $study)
    {
        $this->authorize('update', $study);
        //resto del código

    }

Autorización web en blade.

• Podemos ocultar enlaces usando directivas específicas:

@can('create', App\Study::class)
<div class="float-right>
<a href="/studies">Nuevo estudio</a>
</div>
@endcan

.....

@can('update', $study)
<div class="float-right>
<a href="/studies/{{$study->id}}">Editar</a>
</div>
@endcan

Modelos un poco más a fondo:

• Setters o mutators

• Nomenclatura:

    set{Attribute}Attribute

• Ejemplo:

    class User extends Model
    {
        public function setFirstNameAttribute($value)
        {
            $this->attributes['first_name'] = strtolower($value);
        }
    }

• Getters o accessors

• Permiten modificar o formatear los datos según están recogidos en la base de datos.

• Nomenclatura:

    get{Attribute}Attribute

• Ejemplo:

class User extends Model
{
    public function getFirstNameAttribute($value)
    {
        return ucfirst($value);
    }
}

• Podemos añadir campos calculados:

    public function getFullNameAttribute()
    {
        return "{$this->first_name} {$this->last_name}";
    }

• Podemos incluso hacer que esos campos se añadan cuando serializamos objetos (conversión a JSON).

    class User extends Model
    {
        /**
        * The accessors to append to the model's array form.
        *
        * @var array
        */
        protected $appends = ['is_admin', 'fullName'];
    }

Fechas

• Las fechas se leen como texto de la base de datos

• Laravel tiene una clase específica para tratar fechas y horas llamada Carbon
• Podemos forzar que nuestras fechas hagan casting a esta clase cada vez que se leen de la BBDD.

• Para hacerlo basta con definir la variable $dates:

    class User extends Model
    {
        /**
        * The attributes that should be mutated to dates.
        *
        * @var array
        */
        protected $dates = [
            'seen_at',
        ];
    }

• Una vez hecho esto podemos usar dicho campo como una fecha:

    {{ $user->seen_at->format('d-m-Y') }}
    {{ $user->seen_at->addDays(30) }}
    {{ $user_seen_at->diffInDays($dt->copy()->addMonth()) }}

Laravel como cliente Http

• Una aplicación web también puede ser un cliente Http

• Típicamente podemos hacer que una aplicación web consuma los recursos ofrecidos por una API Rest

• Vamos a crear una nueva instalación de Laravel (laravel20client)

• Vamos a crear un controlador StudyController que consuma los recursos de la API que ya hemos creado.

• Por simplificar, vamos a prescindier de autenticación y autorización

• Ruta api:

    // Route::resource('studies', StudyController::class);
    Route::resource('studies', EstudioController::class);

• Código del controlador en la API

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use App\Models\Study;
use Illuminate\Support\Facades\Validator;

class EstudioController extends Controller
{
    public function index()
    {
        $studies = Study::all();
        // return $studies;
        return response()->json([
            'status' => 200,
            'data' => $studies
        ], 200);
    }

    /**
    * Store a newly created resource in storage.
    *
    * @param  \Illuminate\Http\Request  $request
    * @return \Illuminate\Http\Response
    */
    public function store(Request $request)
    {        
        $rules = [
            'code' => 'required|unique:studies,code|max:6',
            'name' => 'required|max:255',
            'abreviation' => 'required|max:255'
        ];        
        $validator = Validator::make($request->all(), $rules);

        if ($validator->fails()) {
            return response()->json([
                'status' => 'error',
                'errors' => $validator->errors()
            ], 422);                
        }

        $study = Study::create($request->all());
        return response()->json([
            'status' => 'ok',
            'data' => $study
        ], 201);
    }

    /**
    * Display the specified resource.
    *
    * @param  int  $id
    * @return \Illuminate\Http\Response
    */
    public function show($id)
    {
        $study = Study::find($id);
        $this->check404($study);

        return response()->json([
            'status' => 'ok',
            'data' => $study
        ], 200);
    }

    public function update(Request $request, $id)
    {
        $study = Study::find($id);     
        $this->check404($study);

        //si no pasa validación 422
        $rules = [
            'code' => 'required|max:6|unique:studies,code,' . $study->id,
            'name' => 'required|max:255',
            'abreviation' => 'required|max:255'
        ];        
        $validator = Validator::make($request->all(), $rules);
        if ($validator->fails()) {
            return response()->json([
                'status' => 'error',
                'errors' => $validator->errors()
            ], 422);                
        }
        $study->fill($request->all());
        $study->save();
        return response()->json([
            'status' => 'ok',
            'data' => $study
        ], 200);                
    }

    /**
    * Remove the specified resource from storage.
    *
    * @param  int  $id
    * @return \Illuminate\Http\Response
    */
    public function destroy($id)
    {
        $study = Study::find($id);
        $this->check404($study);

        try {
            //status 204: No content
            $study->delete();
            return response()->json([
                'Sin contenido'
            ], 204);
        } catch (\Throwable $th) {
            return response()->json([
                'status' => 'error',
                'message' => 'Borrado fallido. Conflicto',
            ], 409);
        }
    }
    //DRY. Don't Repeat Yourself
    public function check404($study)
    {
        if (!$study) {
            response()->json([
                'status' => 404,
                'message' => 'No se ha encontrado un estudio con ese id'
            ], 404)->send();
            die();
        }
    }

• Crearmos un nuevo proyecto laravel20client

    composer create-project laravel/laravel laravel20cliente

• Añadimos un controlador StudioController que va a gestionar los estudios de nuestra API (en español por diferenciar):

    php artisan make:controller StudioController

• Ahora se trata de añadir rutas y métodos a este controlador para completar el CRUD a través de nuestra API

Index

Show

Store

Update

Delete

Index