Cómo construir una API REST simple en PHP

Spanish (Español) translation by Xiomara Reynoso (you can also view the original English article)

En este tutorial, les enseñaré cómo construir una simple API REST con PHP y MySQL

REST se ha convertido en el estándar de facto cuando se trata de exponer datos a través de API y servicios web. De hecho, la mayoría de las aplicaciones web hoy en día acceden y exponen datos a través de API REST. Con la popularidad de los marcos frontales que pueden consumir la API REST sin esfuerzo, siempre será un más para ti si tu aplicación web expone las API REST.

En este artículo, vamos a construir una simple aplicación de demostración, que te permite obtener una lista de usuarios de la base de datos MySQL a través de un punto final REST.

Prepara el esqueleto

En esta sección, repasaremos brevemente la estructura del proyecto.

Veamos la estructura siguiente.

├── Controller
│   └── Api
│       ├── BaseController.php
│       └── UserController.php
├── inc
│   ├── bootstrap.php
│   └── config.php
├── index.php
└── Model
    ├── Database.php
    └── UserModel.php

Intentemos entender la estructura del proyecto.

index.php: el punto de entrada de nuestra solicitud. Actuará como controlador frontal de nuestra aplicación.
inc/configura.php: tiene la información de configuración de nuestra aplicación. Sobre todo, tendrás las credenciales de la base de datos.
inc/bootstrap.php: usado para atrapar boots en nuestra aplicación incluyendo los archivos necesarios.
Modelo/base de datos.php: la capa de acceso a la base de datos que se utilizará para interactuar con la base de datos subyacente MySQL.
Modelo/Modelo usuario.php: el archivo del modelo de usuario que implementa los métodos necesarios para interactuar con la tabla de usuarios de la base de datos MySQL.
Controlador/Api/Control de bases.php: un archivo de control de base que contiene métodos de utilidad comunes.
Controlador/Api/Controlador de Use.php: el archivo controlador del usuario que contiene el código de aplicación necesario para entretener las llamadas de la API REST.

Así que esa es la configuración básica que vamos a implementar en el resto del artículo.

Crea una base de datos y clases modelo

En esta sección, crearemos una base de datos y la tabla de usuarios. También crearemos clases de modelos necesarias que se usarán para traer a los usuarios de una base de datos.

Crea una base de datos y la tabla de usuarios

Crea la base de datos rest_api_demo ejecutando la siguiente orden en su terminal MySQL. (Accede a esto con la orden mysql de la línea de comando.)

1	$CREATE DATABASE rest_api_demo;

También podrías usar una herramienta como phpMyAdmin si prefieres trabajar con tus bases de datos de esa manera.

Una vez creada la base de datos rest_api_demo, ve y crea la tabla de usuarios ejecutando las siguientes instrucciones.

$use rest_api_demo;
$CREATE TABLE `users` (
  `user_id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  `username` varchar(60) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '',
  `user_email` varchar(100) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '',
  `user_status` int(11) NOT NULL DEFAULT '0',
  PRIMARY KEY (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Eso debería crear la tabla de usuarios en la base de datos rest_api_demo. También querrás poblar esta tabla con unos pocos registros falsos para fines de prueba. ¡Incluye algunos discos y ya estás listo!

Crea clases de modelo

En esta sección, crearemos las clases de modelo necesarias.

Crea la base de datos del Modelo.el archivo de php con el siguiente contenido.

<?php
class Database
{
    protected $connection = null;

    public function __construct()
    {
        try {
            $this->connection = new mysqli(DB_HOST, DB_USERNAME, DB_PASSWORD, DB_DATABASE_NAME);
    	
            if ( mysqli_connect_errno()) {
                throw new Exception("Could not connect to database.");   
            }
        } catch (Exception $e) {
            throw new Exception($e->getMessage());   
        }			
    }

    public function select($query = "" , $params = [])
    {
        try {
            $stmt = $this->executeStatement( $query , $params );
            $result = $stmt->get_result()->fetch_all(MYSQLI_ASSOC);				
            $stmt->close();

            return $result;
        } catch(Exception $e) {
            throw New Exception( $e->getMessage() );
        }
        return false;
    }

    private function executeStatement($query = "" , $params = [])
    {
        try {
            $stmt = $this->connection->prepare( $query );

            if($stmt === false) {
                throw New Exception("Unable to do prepared statement: " . $query);
            }

            if( $params ) {
                $stmt->bind_param($params[0], $params[1]);
            }

            $stmt->execute();

            return $stmt;
        } catch(Exception $e) {
            throw New Exception( $e->getMessage() );
        }	
    }
}

Esta es una clase de capa de acceso a la base de datos, que nos permite establecer una conexión a la base de datos MySQL. Además de la conexión establecida, contiene métodos genéricos como seleccionar y ejecutarDeclaración que nos permite seleccionar registros de una base de datos. No usaremos la clase de base de datos directamente, crearemos clases de modelos correspondientes que amplíen la clase de base de datos para acceder a la base de datos MySQL subyacente.

Después, vamos a crear el Modelo Model/UserModel.php con el siguiente contenido.

<?php
require_once PROJECT_ROOT_PATH . "/Model/Database.php";

class UserModel extends Database
{
    public function getUsers($limit)
    {
        return $this->select("SELECT * FROM users ORDER BY user_id ASC LIMIT ?", ["i", $limit]);
    }
}

Es importante notar que la clase UsuarioModelo amplía la clase de base de datos.

Además, contiene el método ObtenUsuarios, que nos permite seleccionar a los usuarios de la base de datos MySQL. Es obligatorio pasar el parámetro $límite, lo que se asegura de que no seleccionará todos los registros a la vez.

Por supuesto, podría definir más métodos en la clase UsuarioModelo según tus necesidades. Mantendremos las cosas simples en el contexto de este tutorial.

Así que ahora tenemos nuestras clases de base de datos y modelos establecidas. En la siguiente sección veremos cómo crear controles y los archivos que se emiten en nuestra aplicación demo.

Crea componentes de la capa de la aplicación

En esta sección, crearemos los archivos que quedan necesarios para que nuestra aplicación de demo funcione.

El directorio inc

Para empezar, crearemos los archivos de configuración necesarios.

Crea el archivo inc/config.php con el siguiente contenido.

<?php
define("DB_HOST", "localhost");
define("DB_USERNAME", "demo");
define("DB_PASSWORD", "demo");
define("DB_DATABASE_NAME", "rest_api_demo");

Asegúrate de actualizar todos los valores que estés usando en tu instalación.

Después, ve y crea el archivo inc/bootstrap.php con el siguiente contenido.

<?php
define("PROJECT_ROOT_PATH", __DIR__ . "/../");

// include main configuration file
require_once PROJECT_ROOT_PATH . "/inc/config.php";

// include the base controller file
require_once PROJECT_ROOT_PATH . "/Controller/Api/BaseController.php";

// include the use model file
require_once PROJECT_ROOT_PATH . "/Model/UserModel.php";
?>

Primero, hemos iniciado la constante PROJECT_ROOT_PATH con la raíz del directorio de nuestra aplicación. De esta manera, podríamos usar la constante PROJECT_ROOT_PATH para preparar caminos absolutos en nuestra aplicación. Después, incluimos el archivo config.php, que contiene la información de conexión de la base de datos. Finalmente, hemos incluido archivos de control y modelos.

Eso es para establecer los archivos comunes en nuestra aplicación.

El controlador del directorio

En esta sección, implantaremos controles que contengan la mayoría de nuestra lógica de la aplicación.

El archivo BaseController.php

Crea el archivo Controller/Api/BaseController.php con el siguiente contenido. La clase Base de control contiene los métodos de utilidad que son utilizados por otros controladores.

<?php
class BaseController
{
    /**
     * __call magic method.
     */
    public function __call($name, $arguments)
    {
        $this->sendOutput('', array('HTTP/1.1 404 Not Found'));
    }

    /**
     * Get URI elements.
     * 
     * @return array
     */
    protected function getUriSegments()
    {
        $uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
        $uri = explode( '/', $uri );

        return $uri;
    }

    /**
     * Get querystring params.
     * 
     * @return array
     */
    protected function getQueryStringParams()
    {
        return parse_str($_SERVER['QUERY_STRING'], $query);
    }

    /**
     * Send API output.
     *
     * @param mixed  $data
     * @param string $httpHeader
     */
    protected function sendOutput($data, $httpHeaders=array())
    {
        header_remove('Set-Cookie');

        if (is_array($httpHeaders) && count($httpHeaders)) {
            foreach ($httpHeaders as $httpHeader) {
                header($httpHeader);
            }
        }

        echo $data;
        exit;
    }
}

Repasemos rápidamente todos los métodos de clase Base de Control.

El método __call es un método mágico, y así se llama cuando intentas llamar un método que no existe. Estamos aprovechando esta oportunidad para lanzar el error no encontrado de HTTP/1.1 404 cuando alguien intenta llamar un método que no hemos implementado. Si esto te suena confuso, no te preocupes, tendrá más sentido cuando probemos nuestra aplicación en la siguiente sección.

Luego está el método getUriSegments, que devuelve un conjunto de segmentos de URI. Es útil cuando intentamos validar el final REST llamado por el usuario. Después de eso, está el método getQueryStringParams, que devuelve un conjunto de variables de la línea de requeté que se pasan junto con la petición entrante.

Finalmente, está el método sendOutput, que se usa para enviar la respuesta API. Usaremos este método cuando queramos enviar la respuesta API al usuario.

El archivo UserController.php

Después, crea el archivo Controller/Api/UserController.php con el siguiente contenido.

<?php
class UserController extends BaseController
{
    /**
     * "/user/list" Endpoint - Get list of users
     */
    public function listAction()
    {
        $strErrorDesc = '';
        $requestMethod = $_SERVER["REQUEST_METHOD"];
        $arrQueryStringParams = $this->getQueryStringParams();

        if (strtoupper($requestMethod) == 'GET') {
            try {
                $userModel = new UserModel();

                $intLimit = 10;
                if (isset($arrQueryStringParams['limit']) && $arrQueryStringParams['limit']) {
                    $intLimit = $arrQueryStringParams['limit'];
                }

                $arrUsers = $userModel->getUsers($intLimit);
                $responseData = json_encode($arrUsers);
            } catch (Error $e) {
                $strErrorDesc = $e->getMessage().'Something went wrong! Please contact support.';
                $strErrorHeader = 'HTTP/1.1 500 Internal Server Error';
            }
        } else {
            $strErrorDesc = 'Method not supported';
            $strErrorHeader = 'HTTP/1.1 422 Unprocessable Entity';
        }

        // send output
        if (!$strErrorDesc) {
            $this->sendOutput(
                $responseData,
                array('Content-Type: application/json', 'HTTP/1.1 200 OK')
            );
        } else {
            $this->sendOutput(json_encode(array('error' => $strErrorDesc)), 
                array('Content-Type: application/json', $strErrorHeader)
            );
        }
    }
}

Es importante notar que la clase UserController amplía la clase BaseController. Idealmente, esta clase contendría los métodos de acción que están asociados con los puntos finales de REST que están definidos para la entidad usuaria. En nuestro caso, por ejemplo, el punto final /user/list REST corresponde al método listAction. De esta manera, también se pueden definir otros métodos para otros puntos finales de REST.

El método listAction se utiliza para obtener una lista de usuarios de la base de datos MySQL. Contiene toda la lógica del final de /user/list REST.

En el método listAction, hemos iniciado un par de variables como $requestMethod y $arrQueryStringParams en primer lugar. Después, comprobamos que si el usuario ha llamado al punto usuario/lista con el método OBTÉN, de lo contrario no procesaremos más. Finalmente, creamos el objeto UserModel y llamamos al método getUsers para obtener una lista de usuarios de una base de datos. También hemos usado la función json_encode para convertir un orden en un objeto JSON antes de que lo envíen al usuario.

Por último, hemos usado el método sendOutput para enviar la respuesta JSON al usuario. Es importante notar que el valor del entero del tipo de contenido de respuesta está fijado en application/json, ya que estamos enviando la respuesta JSON.

De manera similar, se podrían definir otros métodos también para otros puntos finales.

El archivo index.php

El archivo index.php es el punto de entrada de nuestra aplicación. Veamos cómo se ve.

<?php
require __DIR__ . "/inc/bootstrap.php";

$uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$uri = explode( '/', $uri );

if ((isset($uri[2]) && $uri[2] != 'user') || !isset($uri[3])) {
    header("HTTP/1.1 404 Not Found");
    exit();
}

require PROJECT_ROOT_PATH . "/Controller/Api/UserController.php";

$objFeedController = new UserController();
$strMethodName = $uri[3] . 'Action';
$objFeedController->{$strMethodName}();
?>

Primero, hemos usado funciones parse_url y explotar para iniciar segmentos de URI en la variable de orden $uri. Después, validamos los segmentos de URI. Finalmente, hemos iniciado el controlador de usuario y llamado al método de acción correspondiente.

Con eso hemos creado todos los archivos necesarios en nuestra aplicación demo REST. En la siguiente sección veremos cómo llamarlo desde la perspectiva del usuario final.

Cómo llamar a nuestra API REST

En esta sección veremos cómo llamar a nuestra aplicación de demostración. En nuestra aplicación, hemos construido un punto final REST para obtener una lista de usuarios.

Veamos cómo se ve el URL de nuestro punto final:

1	// https://localhost/index.php/{MODULE_NAME}/{METHOD_NAME}?limit={LIMIT_VALUE}
2	https://localhost/index.php/user/list?limit=20

Si pudieran recordar el archivo index.php, comprobamos que si la variable $uri[2] está fijada en usuario. Además, el valor de la variable $uri[3] funcionaría como nombre del método. En el caso anterior, la variable $uri[3] está fijada en lista. Así, terminaría llamando el método listAction de la clase UserController.

La salida debería verse así:

[
   {
      "user_id":1,
      "username":"Bob",
      "user_email":"bob@gmail.com",
      "user_status":0
   },
   {
      "user_id":2,
      "username":"John",
      "user_email":"john@gmail.com",
      "user_status":1
   },
   {
      "user_id":3,
      "username":"Mark",
      "user_email":"mark@gmail.com",
      "user_status":1
   },
   {
      "user_id":4,
      "username":"Ville",
      "user_email":"ville@gmail.com",
      "user_status":0
   }
]

Como pueden ver, regresa una lista de usuarios como un objeto de JSON. Además, si hay algún error de aplicación, sería devuelto como un objeto de JSON también para fines de devanamiento.

Conclusión

Hoy discutimos cómo construir una aplicación de REST con PHP y MySQL. Para fines de demostración, creamos una aplicación de demostración que permite obtener una lista de usuarios de la base de datos MySQL a través de la API REST.