22. API HTTP

Existen diferentes métodos para enviar consultas HTTP en PHP. El propósito de la API HTTP de WordPress es soportar tantos como sea posibles y utilizar el más adecuado para una consulta en particular.

La API HTTP también se puede utilizar para comunicarse e interactuar con otras APIs como la API de Twitter o la API de Google Maps.

HTTP (HyperText Transfer Protocol) es el protocolo de comunicación de internet. Incluso si esta es tu primera experiencia con HTTP es posiblemente que tú entiendas probablemente más de lo que haces. En su nivel más básico, HTTP trabaja así:

  • Hola, servidor XYZ, ¿podrías pasarme el fichero abc.html?
  • Hola, pequeño cliente, sí, aquí lo tienes.

 

Métodos HTTP

HTTP tiene diferentes métodos, o verbos, que describen tipos de acción particulares. WordPress tiene funciones pre-construidas para tres de los más comunes. Cada vez que se hace una consulta HTTP, se pasa un método con ella para ayudar al servidor a determinar qué tipo de acción está solicitando el cliente.

 

GET

GET se utiliza para recuperar datos. Es de lejos el verbo más comúnmente utilizado. Cada vez que ves una web o  extraes datos de una API, estás viendo el resultado de una consulta GET. De hecho, tu navegador envía una consulta GET al servidor en el que estas leyendo y pide los datos utilizados para construir cada artículo.

 

POST

POST se utiliza para enviar datos al servidor para que el servidor actúe sobre ellos de alguna manera. Por ejemplo, un formulario de contacto. Cuando introduces datos en los campos del formulario y clicas en el botón de enviar, el navegador toma los datos y envía una consulta POST al servidor con el texto que introdujiste en el formulario. Desde allí, el servidor procesará el contacto requerido.

 

HEAD

HEAD es mucho menos conocido que los otros dos. Esencialmente, HEAD es lo mismo que GET, excepto que no recupera datos, sino información sobre los datos. Estos datos describen tanto cosas como la fecha de última actualización de los datos, si el cliente debería ‘cachear’ los datos, qué tipo de datos son, etc. Los navegadores modernos a menudo envían consultas HEAD a las páginas que previamente has visitado para determinar si hay actualizaciones. En caso negativo, puedes ver una copia previamente descargada de la página, en lugar de utilizar ancho de banda innecesariamente descargándote la misma copia.

Todos los buenos clientes API utilizan HEAD antes de realizar una consulta GET para intentar ahorrar ancho de banda. Aunque este método requiera dos consultas HTTP separadas, si HEAD responde que hay nuevos datos, el tamaño de datos con una consulta GET puede ser muy grande. Utilizar sólo GET cuando HEAD responde que hay nuevos datos o que no están cacheados, nos guardará de el uso de mucho ancho de banda y largos tiempos de carga.

 

Métodos personalizados

Hay otros métodos HTTP, como PUT, DELETE, TRACE, y CONNECT. Estos métodos no se verán en este artículo ya que no son métodos pre-construidos para utilizarlos en WordPress, ni es común que las APIs los implementen.

Dependiendo en cómo tu servidor está configurado, puedes implementar métodos HTTP adicionales propios. Siempre es un riesgo salirse de los métodos estándar.

 

Códigos de respuesta

HTTP utiliza códigos de respuesta numéricos y de cadena. Antes de entrar en una larga explicación de cada uno, mejor ver los códigos de respuesta estándar. Puedes definir tus propios códigos de respuesta cuando crees una API, sin embargo, a no ser que necesites soportar tipos de respuesta específicos, es mejor utilizar los estándar. Los códigos personalizados suelen estar en los rangos 1xx.

 

Clases de códigos

El tipo de respuesta se puede ver rápidamente con el dígito izquierdo del código de tres dígitos.

Código de estado Descripción
2xx Consulta realizada
3xx Consulta redirigida a otra URL
4xx Consulta fallida debida a error del cliente. Generalmente, por autenticación inválida o falta de datos.
5xx Consulta fallida debida a error del servidor. Comúnmente por falta o error en los ficheros de configuración.

 

Códigos comunes

Estos son los códigos más comunes que encontrarás.

Código de estado Descripción
200 OK. Consulta realizada
301 Recurso movido permanentemente
302 Recurso movido temporalmente
403 Prohibido. Usualmente debido a una autenticación no válida
404 Recurso no localizado
500 Error interno del servidor
503 Servicio no disponible

 

Tomar (GETear) datos de una API

GitHub prové una excelente API que no requiere registro, para varios aspectos públicos, luego para demostrar algunos de estos métodos, los ejemplos apuntarán a la API GitHub.

Tomar datos es increíblemente simple en WordPress mediante la función wp_remote_get(). Esta función tiene los siguientes dos argumentos:

  • $url. Recurso del que tomar los datos. Debe ser un formato HTTP estándar.
  • $args. Opcional. Puedes pasar una matriz de argumentos para alterar los valores por defecto.

Estos valores por defecto son los siguientes, que pueden ser cambiados con la matriz $args.

  • method – GET
  • timeout – 5 – How long to wait before giving up
  • redirection – 5 – How many times to follow redirections.
  • httpversion – 1.0
  • blocking – true – Should the rest of the page wait to finish loading until this operation is complete?
  • headers – array()
  • body – null
  • cookies – array()

Vamos a utilizar la URL a una cuenta de usuario de GitHub y ver qué tipo de información podemos tomar:

$response contendrá las cabeceras, contenidos y otros meta datos acerca de nuestra solicitud:

Todas las mismas funciones de ayuda se puede utilizar en esta función como con los dos anteriores. La excepción es que HEAD nunca devuelve el ‘body’, por lo que este elemento estará vacío.

 

GET el cuerpo que siempre quisiste

Justo el cuerpo se puede requerir mediante wp_remote_retrieve_body(). Esta función toma un parámetro, la respuesta de cualquier otra función wp_remote_X donde no se recupere el siguiente valor.

Con este ejemplo del recurso GitHub, $body será:

Si no tienes otra operación previa, puedes reducir el código mediante

Muchas de estas funciones se pueden utilizar de la misma manera en una sola línea.

 

GET el código de respuesta

Puedes querer verificar el código de respuesta para asegurarte que tu requerimiento fue correcto. Esto se puede hacer mediante wp_remote_retrieve_response_code().

Si todo es correcto, $http_code contendrá 200.

 

GET una cabecera específica

Si deseas recuperar una cabecera específica, puedes hacerlo con wp_remote_retrieve_header(). Esta función tiene dos parámetros:

  • $response. La respuesta de la llamada get.
  • $header. Nombre de la cabecera a recuperar.

Para recuperar la última cabecera modificada:

$last_modified contendrá ‘[last-modified] => Fri, 05 Oct 2012 04:39:58 GMT’. Además, puedes recuperar todas las cabeceras en una matriz con wp_remote_retrieve_headers( $response ).

 

GET con autenticación básica

Las APIs securizadas proveen uno o más diferentes tipos de autenticación. Uno común, no demasiado seguro, es la Autenticación Básica HTTP. Se puede utilizar en WordPress pasando ‘Authorization’ al segundo parámetro de la función wp_remote_get(), así como a las otros funciones de métodos HTTP.

 

POSTear datos a una API

Los mismo métodos auxiliares (wp_remote_retrieve_body(), etc) están disponibles para todas las llamadas a métodos HTTP, y se utilizan de la misma forma.

POSTear datos se hace mediante la función wp_remote_post(), y tiene exactamente los mismo parámetros que wp_remote_get(). Notarás aquí que debes pasar todos los elementos en el segundo parámetros. El Codex provee los valores por defecto aceptables. Sólo necesitas vigilar los datos que estás enviando, pues los otros valores serán por defecto.

Para enviar datos al servidor necesitas crear una matriz asociativa de datos. Estos datos se asignarán al valor ‘body’. Del lado servidor el valor aparecerá en la variable $_POST como esperas. Por ejemplo, si body => array( ‘myvar’ => 5 ) en el servidor, $_POST[‘myvar’] = 5.

Aunque GitHub no acepta POST a la API utilizada en el ejemplo anterior, este ejemplo pretenderá que sí lo hace. Si quieres POSTear datos a una API, necesitas contactar a los mantenedores de la API y obtener la API key o alguna otra forma de autenticación. Esto símplemente prueba que tu aplicación tiene permiso para manipular datos en la API de la misma forma que si te registras en un sitio web como un usuario.

Asumamos que estamos enviando un formulario de contacto con los siguientes campos: nombre, email, sujeto, comentario. Para preparar el ‘body’, haz lo siguiente:

Ahora necesitamos establecer el resto de valores que se pasarán al segundo parámetro de wp_remote_post()

Entonces, por supuesto, hacer la llamada

 

HEAD fuera del uso de ancho de banda

Puede ser muy importante, y en ocasiones lo requiere la API, verificar el estado de un recurso utilizando HEAD antes de recuperarlo. En APIs de alto tráfico, GET a menudo está limitado a un número de consultas por minuto u hora. No hay necesidad de incluso intentar una consulta GET a no ser que la consulta HEAD muestre que los datos de la API han sido actualizados.

Como se menciona antes, HEAD contiene datos de si los datos han sido o no actualizados, si los datos han sido cacheados, cuando expira la copia cacheada, y a veces un tiempo límite de las consultas a la API.

Volviendo atrás al ejemplo GitHub, aquí hay pocas cabeceras en las que mirar. Muchas de estas cabeceras son estándar, pero siempre puedes verificar la documentación de la API para asegurarte de que entiendes qué cabeceras se denominan cómo, y su propósito.

  • x-ratelimit-limit. Número de consultas permitidas en un período de tiempo.
  • x-ratelimit-remaining. Numero de consultas permitidas restantes en un período de tiempo.
  • content-length. Largo del contenido en bytes. Puede ser útil para advertir al usuario si el contenido es muy largo.
  • last-modified. Cuándo fue por última vez modificado el recurso. Muy útil para herramientas cacheadas.
  • cache-control. Cómo debe el cliente tomar el caché.

El siguiente código verificará el valor HEA de una cuenta de usuario de GitHub:

$response será similar a

Todas las funciones útiles similares se pueden utilizar en esta función como con las dos anteriores. La excepción aquí es que HEAD nunca devuelve el body, por lo que este elemento siempre está vacío.

 

Hacer cualquier tipo de consulta

Si necesitas hacer una consulta utilizando un método HTTP que no está soportado por ninguna de las anteriores funciones, no te preocupes. La gran comunidad de gente desarrollando WordPress ya pensó en ello y proveyó wp_remote_request(). Esta función toma los mismos dos parámetros que wp_remote_get(), y te permite especificar también el método HTTP. Qué datos necesitas pasar es tu cuestión.

Para enviar un método DELETE de ejemplo, debes tener algo similar a:

 

Introducción al caché

‘Cachear’ es una práctica por la cual aquellos objetos comúnmente utilizados o los objetos que requieren excesivo tiempo para construir son guardados dentro de un objeto almacén rápido para recuperarlos rápidamente en posteriores consultas. Esto previene la necesidad de gastar tiempo recuperando y construyendo el objeto otra vez. La cache es un vasto sujeto que forma parte de la optimización de un sitio web y podría formar una serie entera de artículos por si misma. Lo que sigue a continuación es simplemente una introducción al ‘cacheo’ y una simple, efectiva y rápida forma de ajustar una cache para respuestas API.

Qué deberá responder la caché de tu API? Muchos consultores te dirán que el caudal en APIs externas mejorará la actuación de tu web reduciendo el montante de conexiones y procesando sus ejecuciones, como el coste de ancho de banda, pero en ocasiones esto simplemente no es verdad.

Es un fino acto de equilibrio entre la velocidad en que tu servidor puede enviar datos y el montante de tiempo que toma el servidor remoto para procesar la consulta, construir los datos y enviarlos de vuelta. El segundo aspecto clarificador es que algunas APIs tienen un número limitado de consultas en un periodo de tiempo, y posiblemente un límite del número de conexiones por una aplicación en una vez. El ‘cacheo’ ayuda a resolver estos problemas colocando una copia de los datos en tu servidor hasta que necesitan ser refrescados.

 

¿Cuándo deberás cachear?

La respuesta automática a esto es ‘siempre’, pero otra vez hay veces que no. Si estás tratando con datos en tiempo real o la API específicamente dice no al caché en las cabeceras no querrás cachear, pero para las otras situaciones generalmente es una buena idea cachear cualquier recurso requerido de una API.

 

WordPress transitorio

WordPress transitorio provee una manera conveniente de guardar y utilizar objetos cacheados. La vida transitoria para una cantidad de tiempo especificada, o hasta que necesitas que expire cuando un recurso de una API ha sido actualizado. Utilizar la funcionalidad transitoria en WordPress puede ser la forma más fácil de usar un sistema de caché que encontrarás. Sólo hay tres funciones para hacer el trabajo duro.

  • Cachear un objeto ( seleccionar una transitoriedad )

Cachear un objeto se hace con la función set_transient(). Esta función tiene los siguientes 3 parámetros:

  1. $transient. Nombre de la transitoriedad para una referencia futura.
  2. $value. Valor de la transitoriedad.
  3. $expiration. Cuántos segundos guardar hasta que expire

Un ejemplo de cachear la respuesta de información de usuario de GitHub durante una hora, sería:

 

  • Tomar un objeto cacheado ( tomar una transitoriedad )

Tomar un objeto cacheado es bastante más complejo que cachearlo. Necesitas requerir el objeto, pero entonces también necesitas verificar para ver si ha expirado y, en tal caso, requerir los datos actualizados. Generalmente la llamada set_transient() se hace dentro de la llamada get_transient(). He aquí un ejemplo de tomar los datos cacheados del perfil de usuario de GitHub:

 

  • Borrar un objeto cacheado (borrar una transitoriedad)

Borrar un objeto cacheado es la más fácil de todas las funciones de transitoriedad, símplemente pasar un parámetro del nombre de la transitoriedad y ya lo has hecho.

Para eliminar la información de usuario de GitHub:

 

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *