6. Servicios Web con PHP

En este tema aprenderemos a:

  1. Entender los servicios web y su arquitectura

  2. Consumir APIs desde PHP

  3. Crear APIs en PHP

Está organizado en 8 talleres de unas 3 sesiones de clase. En total unas 24 sesiones de clase más tu trabajo en casa.

La dedicación depende del conocimiento previo, motivación y capacidad de aprendizaje del estudiante para esa sesión en concreto.

Video Clase

6.1. Servicios Web (W3C)

Video Clase

  1. Servicios Web W3C:

    1. Arquitectura estandarizada por el W3C (complejo)

      https://www.w3.org/TR/ws-arch/images/intro_ws_roles.gif

    2. Define los componentes, protocolos y estándares

      1. El mensaje. XML

      2. El protocolo. XML-RPC -> SOAP -> API RESTful

      3. La descripción de los servicios: WSDL

      4. Descubrimiento de los servicios: UDDI

    3. Elementos (arquitectura SOAP):

      1. El publicador. Describe los que hay en formato WSDL

      2. El proveedor de servicios (Service Provider). Da el servicio solicitado por el cliente

      3. El Consumidor (Service Consumer Proxy). Usa las funciones a través de SOAP

      https://upload.wikimedia.org/wikipedia/commons/thumb/5/5e/Webservices-en.svg/440px-Webservices-en.svg.png

  2. Ejemplo de API SOAP (WebSphere Service Registry and Repository )

    1. La publicación es directamente en su web.

    2. Tiene una estructura y unos tipos descritos en varios documentos WSDL

    3. Necesitas crear un cliente SOAP en base a un WSDL

    4. Usas las operaciones y tipos descritos:

      1. Por ejemplo el tipo DataGraphType (que irá dentro del mensaje SOAP en algún caso)

      2. Por ejemplo la operación retrieve (que describe la operación y el resultado)

Actividad T06-A01. Conceptos de servicios web

Revisando el material para leer, a ver si logras resolver las siguientes cuestiones:

  1. ¿Cual sería la diferencia entre servicio y protocolo?

  2. ¿Cual sería la diferencia entre protocolo y mensaje?

  3. ¿Puedes entender los componentes de un Servicio Web?

  4. ¿Qué elementos encuentras en un mensaje SOAP? Ejemplo Mensaje SOAP

  5. ¿Qué elementos encuentras en un archivo WSDL? Ejemplo Archivo WSDL

  6. ¿Cual sería uno de los ejemplos de «acciones» a desarrollar? En el archivo anterior

  7. El archivo WSDL, ¿qué tipo de estándar utiliza?

  8. El protocolo SOAP, ¿obliga a usar HTTP?

  9. ¿Qué diferencia ves al componente Publicación del servicio frente al proveedor?

  10. ¿Un API es obligatoriamente un servicio web?

6.2. Servicios Web API REST

Video Clase

  1. Un web service es un API (pero al revés no siempre)

    1. ¿Entonces qué es un API?

      1. Es un concepto amplio

      2. Hay que incluir el apellido para incluir la arquitectura

    2. Diferencia entre API y Servicio Web

      1. No son lo mismo (pero se parecen mucho)

      2. Uno es un caso particular de otro

      3. El problema a resolver es el mismo: servicios interoperables, accesibles y estándar

      4. Un par de criterios para escoger un tipo específico de API:

        1. la dirección del recurso (múltiple o única)

        2. lo estricto del servicio (integridad)

      5. Ejemplos de APIs para usar en servicios web: API SOAP, API RESTful, API HTTP o p.ej. API WebSocket (P2P).

  2. Arquitectura de Microservicios

    1. No tiene que ver con Web Service, pero se usa como infraestructura de soporte

    2. Arquitectura Monolítica vs Microservicios

    3. Principio de diseño KISS : un servicio -> una tarea -> un responsable

    4. Comunicación con APIs ligeras e independientes

    5. Arquitectura muy flexible y escalable

      https://d1.awsstatic.com/Developer%20Marketing/containers/monolith_1-monolith-microservices.70b547e30e30b013051d58a93a6e35e77408a2a8.png

  3. En contexto web: API -> Servicio web a través de un API generalmente con arquitectura REST (API RESTful)

  4. Arquitectura web de tipo REST (Transferencia de Estado Representacional ):

    1. Componentes:

      1. Protocolo C/S sin estado: basada en HTTP (Repasa bien su uso: Servicios Web (HTTP))

      2. Respuesta en Mensaje : texto (.txt, .csv, .json) o texto con marcado (HTML / XML)

      3. Operaciones bien definidas en base a operaciones CRUD

        Operaciones en API REST

        Operación

        Método HTTP

        CREATE

        POST

        READ

        GET

        UPDATE

        PUT

        DELETE

        DELETE

      4. Direcccionamiento e Identificación estándar: URL (bueno, URI)

  5. Plantea varias ventajas (frente a los WebService o API de SOAP):

    1. Más flexible

    2. Más ligera

    3. Mejor rendimiento

  6. Hay un móntón de APIs para desarrollar de uso público y libre

Actividad T06-A02. Investigación sencilla sobre un API

Sobre un API de ejemplo que conozcas (o busques)

  1. ¿Cual es su documentación de referencia?

  2. ¿Cual sería un ejemplo de URL a usar?

  3. ¿En qué formato devuelve las respuestas?

  4. ¿Qué tipo de operaciones permite?

  5. ¿Es de acceso libre o necesita algún tipo de clave?

  6. ¿En qué lenguaje de programación está hecha?

  7. ¿Qué servidor web utiliza?

  8. ¿Para qué te serviría a tí?

  9. ¿Qué diferencia hay entre un API Web del Navegador y un Servicio Web API REST?

6.3. Consumir el API

Video Clase

  1. Un API se puede consumir de formas diferentes:

    1. Front - End: Desde el cliente (Programacion Asíncrona con AJAX)

    2. Back - End: Desde el Servidor

    3. Híbrido: uso mixto según necesidades

  2. ¿Cómo lo consumes?

    1. Consultas la documentación:

      1. Un ejemplo sencillo: API Chuck Norris Jokes (chistes en categorías)

      2. Uno complejo: API OpenWeather (tiempo meteorológico en una ubicación geográfica)

    2. Cada URL/URI ofrece una funcionalidad concreta y:

      1. Unos parámetros de entrada

      2. Una salida (recurso de respuesta)

    3. Consumir el API significa:

      1. Consultar el recurso (con cualquier Cliente Web (y herramientas)) (a veces auténticándose)

      2. Ver la respuesta. Una vez devuelta, el API se olvida del cliente (arquitectura sin estado)

  3. Autenticación en APIs REST (necesitas consultar la documentación particular):

    1. Pública: sin autenticación

    2. Autenticación HTTP: basado en credenciales usuario/contraseña con métodos HTTP (básica / digest).

    3. Basada en claves de acceso (tokens). Por ejemplo Autenticación en OpenWeather

      1. Con clave de acceso específica

      2. O usando una versión avanzada (típicamente usando JWT).

    4. Uso de Autenticación (API) de terceros: OAuth por ejemplo Autenticación con Youtube

Actividad T06-A03. Probar dos ejemplos de API

Como cliente del API (Best API Clients ), que guarde en un archivo, puedes usar:

  1. Un rastreador web (wget / curl)

  2. Un navegador web con alguna extensión para modificar las cabeceras (de autenticación)

  3. Un software GUI o librería de programación específica

El ejercicio consiste en hacer una prueba de consumo de las dos APIs de ejemplo. Ideal ver la respuesta en un archivo de texto (es lo que utilizarías en desarrollo).

  1. API Chuck Norris Jokes . API pública con chistes en categorías

    1. Consulta de un chiste aleatorio

    2. Consulta un chiste aleatorio pero de una categoría concreta

    3. Consulta las diferentes categorías disponibles

    4. Consulta los chistes que contengan la palabra «spain»

  2. API OpenWeather API privada, con autenticación con clave, para consultar el tiempo meteorológico

    1. Crea tu clave para usar el API

    2. Consulta el tiempo en Vigo (VGO), hoy

    3. Consulta el tiempo en Santo Domingo (SDQ), hoy

    4. Consulta el tiempo en Vigo (VGO), el 15 de Julio de 2021

    5. Consulta el tiempo en Santo Domingo (SDQ), hoy, el 15 de Julio de 2021

6.4. Cliente API en PHP

Video Clase

  1. Y, por concretar, se puede consumir un servicio web con php . Es decir usar php

    1. Como cliente del API (cliente http)

    2. Como generador de páginas web dinámicas (usando la respuesta)

  2. Ojo a entender la secuencia (síncrona) de carga. Los pasos serían:

    1. Uso el cliente

      1. Lo más sencillo y rápido: function.file-get-contents

      2. Para añadir cabeceras http hay que crear un contexto al flujo function.stream-context-create

    2. Recojo y guardo la información

    3. Proceso esa información (para mi página o lo que necesite)

      <?php

       # Array con parámetros clave = valor que ...
       $data = array ('foo' => 'bar', 'bar' => 'baz');

       # ... tienes que codifificar como url (url encoded)

       $data = http_build_query($data);

       # Y construyes la petición http, con sus cabeceras y            sus datos (porque vas a usar el método POST)

       $context_options = array (
            'http' => array (
                'method' => 'POST',
                'header'=> "Content-type: application/x-www-form-urlencoded\r\n"
                    . "Content-Length: " . strlen($data) . "\r\n",
                'content' => $data
            )
       );

       # Y creas el contexto para ese flujo (stream) concreto

       $context = context_create_stream($context_options)
       $response = file_get_contents('URL_API', false, $context);
?>

Actividad T06-A04a. Aplicación Web con un API (Ejemplo 1)

Usa PHP usando el API Chuck Norris Jokes para crear una pequeña aplicación web que:

  1. Me muestre un chiste aleatorio (chiste, la fecha de actualización y la categoría a la que pertenece).

  2. Que me muestre una lista de todas las categorías disponibles. La lista tiene un url para mostrar un chiste de esa categoría en concreto

  3. Y si quiero, que me muestre un chiste aleatorio, de una búsqueda por un texto concreto (por ejemplo «spain»)

Actividad T06-A04b. Aplicación Web con un API (Ejemplo 2)

Usa PHP para generar una aplicación web sencilla que usando el API OpenWeather me muestre, para una ubicación previamente seleccionada:

  1. El tiempo y humedad (hoy y el 15 de Julio del 2021)

  2. Presión Atmosférica y porcentaje de nubosidad (hoy y el 15 de Julio del 2021)

  3. Una descripción del tiempo en esa ubicación

6.5. Crear API REST en PHP

Video Clase

  1. Muy usado como desarrollo servidor (back-end)

    1. Microservicio HTTP: infraestructura fiable, de alto rendimiento y fácil de desplegar

    2. Con la misma infraestructura se puede desplegar desde algo muy sencillo, a algo realmente complejo

  2. Planificar tu API:

    1. ¿Qué va a hacer? Funcionalidad

    2. ¿Desde donde va a servir? EndPoint/s

    3. ¿Qué recursos va a usar? Formato de respuesta (mensajes y estado)

    4. ¿Qué operaciones va a permitir? Operaciones CRUD

    5. ¿Qué tipo de autenticación y autorización vas a utilizar?

  3. Funciona el ciclo de desarrollo iterativo de sofware (nada sale bien a la primera)

  4. Para crear APIs debes usar urls semánticas o amigables (sin extensión). Es decir (mapping url paths):

    1. En vez de http://www.miweb.com/index.php?seccion=noticias&id_noticia=133 (lo que necesita el back-end)

    2. Procesarlo a http://www.miweb.com/noticias/133 (por ejemplo). Que es lo que ve el usuario y ofrece el servidor web

    3. El servidor web que uses, tiene que tener un módulo de reescritura :

      1. Activa la posibilidad de reescribir (redireccionar) un url de …

      2. un origen (patrón, en el usario) a un destino (url a la capa de aplicación)

Actividad T06-A05a. Uso de urls amigables

Depende del servidor web que utilices, pero la funcionalidad debería ser la misma. Tres ejemplos, sobre $TU_WEB como directorio principal. Supongamos https://www.tuweb.com/apis/

  1. $TU_WEB/noticias/133 se convierte en $TU_WEB/index.php?seccion=noticias&id_noticia=133

  2. $TU_WEB/pedido/25/128 se convierte en $TU_WEB/pedido?id=128&categoria=25

  3. $TU_WEB/articulo/titulo-del-articulo se convierte en $TU_WEB/a/index?title="Título del Artículo"

Actividad T06-A05b. Crear 3 APIs sencillas con PHP

  1. Crear un API que devuelva un color aleatorio de una lista previa (en texto utilizable como valor de color CSS). Endpoint: /api/colores . Formato texto plano

  2. Crear un API de refranes españoles . Devolverá un refrán aleatorio, en texto puro de entre 100 escogidos previamente. Endpoint: /api/refranes . Formato texto plano

  3. Crear un API similar al anterior, pero que devuelva tres refranes en un objeto JSON, con un campo extra que diga el orden: primero, seguro y tercero. Endpoint /api/refranes-json . Formato JSON

6.6. Añadir Funcionalidad a un API

Video Clase

  1. Puedes añadir funcionalidad a un API básico:

    1. Con parámetros en el url (similar a un formulario):

      1. Uso un sólo programa

      2. Puedo servir en varios urls …

      3. … porque configuro urls semánticas en función de los parámetros

        $TU_WEB/tu_api?param1=N&param2=M -> $TU_WEB/N/M

    2. Añado formato más complejo (por ejemplo JSON)

      1. Puedo añadir diferentes formatos en la respuesta …

      2. … utilizando urls semánticas y con un parámetro GET

      3. Con la misma funcionalidad, la respuesta es la misma

        $TU_WEB/tu_api?formato=csv o ...
$TU_WEB/tu_api?formato=xml

    3. Y … podría seguir, porque la complejidad podría ser:

      1. a nivel de programación. No es lo mismo un API de refranes que un API del tiempo

      2. No es lo mismo un API que hace un cálculo simple, que una que consulta varios almacenes de datos y diferentes servicios

  2. Vamos a revisar un ejemplo completo, para entender:

    1. La reescritura de urls

    2. La simulación el envío de datos (usando valores estáticos para probar el API)

    3. Definir la configuración básica (nombre de los scripts, textos de ayuda, etc)

    4. Configuración de la lógica principal (puede ser algo sencillo o usar programación más compleja)

Actividad T06-A06. 3 APIs sencillas con PHP

  1. Crea un API que devuelva el número de caracteres de una cadena de texto. Endpoint /apis/contador. Formato texto plano.

  2. Crea un API que me devuelva el IMC de una persona (muy bien explicado aquí ). Endpoint /apis/imc/. Formato texto plano (tendrás que resolver cómo enviar los parámetros, hay diferentes opciones). Ideal en el url.

  3. Crea un API que reciba un JSON con nombre y apellidos y devuelva un texto con el nombre completo (nombre y apellidos). EndPoint: /apis/construir-nombre . Formato texto en crudo. Aquí el problema es usar POST y la información.

6.7. API REST con POO

Video Clase

Uso completo de un API usando POO (Programación Orientada a Objetos con PHP)

Actividad T06-A07. API completa de gestión de usuarios

Implementar un API que permita gestionar usuarios, con un almacén en un archivo de texto.

Algunos pasos recomendados (vete paso a paso):

  1. Crea usuarios.php para que recoja la «operación a realizar» y simplemente la escriba

  2. Crea la clase principal Usuarios con todas las propiedades y operaciones

  3. Definir las operaciones de lectura (R, la más sencilla)

  4. Definir las operaciones de escritura (CUD)

    1. Usando parámetros (GET) o …

    2. Usando el cuerpo del mensaje (POST/PUT)

  5. Resolver la persistencia de los datos (en principio en archivos de texto o serializando los objetos).

6.8. API RESTful

Video Clase

  1. RESTful significa que cumple todas las especificaciones REST:

    1. Un API básico suele ser simplemente leer (R)

    2. Un API complejo (en las operaciones) implica actualizar (U), borrar (D) y crear (C) datos.

  2. El uso de urls semánticas ya se hace imprescindible

  3. El uso de envío de datos también:

    1. En el cuerpo del mensaje (vía POST)

    2. En el url (vía GET)

  4. Y, por último, el uso de algún tipo de autenticación

Actividad T06-A08. Configurar el servidor para usar URI exclusivamente

Modificar el ejercicio de la sesión anterior para que use sólo url (y no parámetros GET)