Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. WordPress

Introducción a la REST API de WordPress

by
Difficulty:BeginnerLength:LongLanguages:
This post is part of a series called Introducing the WP REST API.
WP REST API: Setting Up and Using Basic Authentication

Spanish (Español) translation by Elías Nicolás (you can also view the original English article)

Desde su creación en 2003, WordPress ha pasado de ser una mera plataforma de blogs a un sistema de gestión de contenidos de pleno derecho. En los últimos años, ha madurado lo suficiente como para satisfacer la necesidad de la gran mayoría de la audiencia en línea y esta es la razón por la que está potenciando más del 20% de la Web en la actualidad.

Con muchas nuevas características que se agregan a WordPress, una de las últimas incorporaciones es la API REST que permite que otras aplicaciones y plataformas interactúen con WordPress. Es una adición revolucionaria que ayudará a los desarrolladores a crear aplicaciones personalizadas y sistemas integrados con WordPress. Dado que proporciona la capacidad de agregar y recuperar contenido de cualquier otro cliente o sitio, sin la necesidad de tener WordPress instalado en ese sitio, permite que WordPress se use con cualquier lenguaje de programación o plataforma.

En esta serie de varias partes, analizaremos la API WP REST y cómo podría usarse para crear experiencias de usuario que de otro modo serían imposibles o al menos arduas con WordPress. Primero analizaremos conceptos básicos, como REST y JSON, y luego exploraremos las opciones disponibles a través de la API WP REST.

A continuación hay algunos recursos que considero útiles para conceptos básicos, como HTTP, REST y JSON. Le recomiendo que los eche un vistazo si aún no lo ha hecho:

Antes de comenzar con nuestro tema, echemos un vistazo breve a lo que realmente es la arquitectura REST y también familiarícese con su terminología común.

Regreso a la escuela con REST

Para comenzar con el tema, echemos un vistazo a la arquitectura REST (Representational State Transfer) y algunos de sus conceptos más comunes. Comprenderlos es esencial cuando se desarrollan aplicaciones usando el estilo arquitectónico REST.

REST es un estilo arquitectónico que ayuda a crear y organizar un sistema distribuido. Describe la web como una aplicación de hipermedia distribuida cuyos recursos vinculados se comunican intercambiando representaciones de estado de recursos resource.

Los recursos son los principales componentes de la arquitectura REST. De hecho, son los principales componentes básicos de la propia web en la medida en que la web a veces se denomina "orientada a recursos".

Cuando hablamos de WordPress, estos recursos son entidades discretas como posts, pages, comments, users, y tipos de publicaciones personalizadas, etc. Para interactuar con los recursos, se utilizan los URI (Identificador Uniforme de Recursos), y como su nombre lo indica, es un identificador para un recurso.:

Un servicio RESTful trata los URI como la forma principal de abordar un recurso subyacente. Este recurso puede tener varias representaciones. Por ejemplo, un archivo de imagen podría estar disponible en formatos .JPG, .GIF o .PNG. La relación entre los recursos y los URI es de uno a muchos. Un URI solo puede señalar a un recurso específico pero un recurso puede tener más de un URI.

La lista de todos los recursos soportados actualmente por la API WP REST es la siguiente

  • Publicaciones
  • Páginas
  • Media
  • Tipos de publicaciones personalizadas
  • Post Meta
  • Revisiones
  • Comentarios
  • Condiciones
  • Usuarios

Podemos realizar diferentes acciones en estos recursos utilizando verbos HTTP.

Verbos HTTP

Una API REST básicamente permite realizar operaciones CRUD (Crear Leer Borrar Actualizar) en recursos usando HTTP. Para este propósito, REST utiliza un conjunto limitado de verbos de solicitud HTTP que son los siguientes:

  1. GET: se usa para leer o recuperar un recurso
  2. POST: se usa para crear un nuevo recurso
  3. PUT: se usa para actualizar un recurso
  4. DELETE: se usa para eliminar un recurso
  5. HEAD: Se usa para verificar si un recurso existe sin devolver su representación
  6. OPTIONS: se usa para recuperar todos los verbos soportados por un recurso

En un servicio RESTful, estos verbos tienen un significado bien definido. Los primeros cuatro verbos de la lista anterior son parte de las acciones de CRUD, es decir, recuperan, crean, actualizan y eliminan entidades. Los dos últimos verbos ayudan a un cliente a determinar si existe un recurso y qué verbos HTTP están disponibles para que realice más operaciones.

Una solicitud GET recupera información y es idempotente, es decir, un cliente puede llamarla muchas veces pero no afectará el estado de un recurso.

Para obtener todas las publicaciones usando la API WP REST, usamos el siguiente endpoint:

El punto final anterior devolverá una colección de todas las entidades de publicación.

Cuando se desencadena el siguiente punto final, devuelve una entidad particular, es decir, una publicación que tiene una identificación de 100:

Una solicitud POST crea una nueva entidad y una solicitud PUT reemplaza esa entidad con una nueva versión.

La siguiente solicitud POST se puede utilizar para crear una nueva publicación (enviando a lo largo del cuerpo de la solicitud que veremos en la última parte de la serie) usando la API WP REST:

Y la siguiente solicitud PUT actualizará una publicación que tenga una identificación de 100:

Una solicitud DELETE borra un recurso del sistema. Este tipo de solicitud, junto con la solicitud PUT, son repetibles, lo que significa que llamar a estos métodos tendrá el mismo efecto en el sistema. Por ejemplo, si llama una solicitud PUT varias veces en un recurso (con los mismos argumentos), el resultado será el mismo. Lo mismo aplica para una solicitud DELETE. Eliminar un recurso varias veces tendrá el mismo efecto, es decir, se eliminará el recurso (o se devolverá un error en el caso de un recurso ya eliminado).

Además de estas acciones CRUD, un servicio RESTful proporciona dos verbos más que son OPTIONS y HEAD. Estos verbos son útiles cuando un cliente necesita verificar qué recursos están disponibles en el sistema y qué acciones respaldan, proporcionando así una manera auto-documentada para que el cliente explore más el sistema y realice acciones. Veremos estos dos métodos en acción más adelante en este tutorial.

Más sobre rutas y Endpoints

Tenga en cuenta que en el primer ejemplo anterior, utilizamos el siguiente endpoint:

Los puntos finales son funciones que están disponibles a través de la API y realizan varias acciones, como la recuperación de publicaciones (que estamos haciendo arriba), la creación de un nuevo usuario o la actualización de una meta de publicación. Alternativamente, podemos decir que un punto final desencadena un método que realiza una tarea específica. Estos puntos finales dependen del verbo HTTP asociado a ellos. En el ejemplo anterior, estamos usando el verbo GET para recuperar todas las publicaciones.

La ruta para el endpoint anterior es la siguiente:

Una ruta es básicamente un nombre para acceder al endpoint. Una ruta puede tener múltiples puntos finales basados en verbos HTTP. Entonces, la ruta anterior tiene el siguiente punto final para crear una nueva publicación:

Este punto final, cuando se desencadena con los parámetros proporcionados, creará una nueva entidad de publicación.

Considera la siguiente ruta:

Esta ruta apunta a la entidad Post que tiene una identificación de 100. Tiene los siguientes tres puntos finales:

  1. GET wp/v2/posts/100: que se puede usar para recuperar la publicación que tiene una identificación de 100. Activa el método get_item().
  2. PUT wp/v2/posts/100: se puede usar para actualizar la publicación que tiene una identificación de 100. Activa el método update_item().
  3. DELETE wp/v2/posts/100: elimina la publicación que tiene una identificación de 100. Activa el método delete_item().

Aprenderemos más sobre los aspectos internos de la API WP REST, su estructura de clase y los métodos internos en la parte final de esta serie.

Ahora refresquemos nuestro conocimiento sobre algunos códigos de respuesta HTTP comunes y lo que significan.

Códigos de respuesta HTTP

Un servidor responde a una solicitud devolviendo una respuesta que contiene un código de estado HTTP. Estos códigos son números con significados predefinidos asociados a ellos. Por ejemplo, cualquiera que use la web estaría familiarizado con el código de estado 404 que resume que no se encontró el recurso que el usuario estaba buscando.

La respuesta del servidor también depende del tipo de verbo HTTP o método que usemos en la solicitud enviada, como veremos a continuación.

Los siguientes son algunos códigos de respuesta HTTP comunes junto con sus significados, que encontraremos al trabajar con la API WP REST y sus significados:

  • 200 - OK: significa que la solicitud se ha completado con éxito y el servidor ha devuelto la respuesta. Generalmente se devuelve después de una solicitud GET exitosa.
  • 201 - Created: generalmente se devuelve después de una solicitud POST exitosa. Resume que el recurso ha sido creado.
  • 400 - Bad Request: se devuelve desde el servidor cuando se envió una solicitud con algunos parámetros faltantes o no válidos. Por lo general, se devuelve en respuesta a las solicitudes POST o PUT.
  • 401 - Unauthorized: significa que el usuario no estaba autorizado para realizar determinada acción. Por ejemplo, un usuario intentó crear o eliminar un recurso sin proporcionar credenciales de autenticación.
  • 403 - Forbidden: Significa que el servidor entendió la solicitud pero se negó a completarla debido a la autenticación. Sucede cuando un usuario proporciona credenciales de autenticación pero no tiene suficientes derechos para realizar la acción.
  • 404 - Not Found: el más (en) famoso de todos los códigos de estado. Resume que no se encontró un recurso que el usuario estaba buscando.
  • 405 - Method not Allowed: significa que el recurso no admite un verbo HTTP proporcionado en la solicitud. Un ejemplo podría ser un usuario que intenta actualizar un recurso de solo lectura.
  • 410 - Gone: Significa que un recurso se ha movido a otra ubicación. Un ejemplo podría ser tratar de eliminar un recurso ya eliminado que se ha movido a la papelera.
  • 500 - Internal Server Error: se devuelve cuando un servidor encuentra una condición inesperada y no completa la solicitud.
  • 501 - Not Implemented: significa que el servidor no admite la funcionalidad para completar la solicitud. Generalmente ocurre cuando un servidor recibe un método de solicitud que no reconoce.

Examinaremos estos verbos HTTP y códigos de respuesta más de cerca cuando realmente comencemos a trabajar con la API. Pero antes de eso, echemos un vistazo a las razones para usar REST API con WordPress y las ventajas que ofrece tanto para el desarrollador como para el usuario. Después de todo, necesito que estés genuinamente interesado en acompañarme durante esta serie.

¿Por qué utilizar la API JSON REST para WordPress?

REST y JSON juntos proporcionan un mecanismo para crear aplicaciones potentes usando el back-end de WordPress. Los mejores ejemplos son las aplicaciones móviles que requieren el intercambio de datos entre el cliente (el dispositivo) y el servidor. Teniendo en cuenta las limitaciones de ancho de banda al usar datos móviles, JSON proporciona una alternativa ligera a las soluciones basadas en XML.

Como JSON es un formato basado en texto para almacenar datos, se puede usar sin problemas con la mayoría de los lenguajes de programación. Por lo tanto, JSON sirve como un conector global al intercambiar datos entre diferentes plataformas que es igualmente legible tanto por las máquinas como por los humanos.

Con el uso de API como la que se está discutiendo, el contenido de su sitio de WordPress no se limita solo a sí mismo, sino que otros sitios y clientes pueden acceder a él. Como API expone algunas partes de la funcionalidad interna, los clientes remotos pueden interactuar con su sitio para actualizar o crear contenido nuevo. También permite recuperar cierto contenido de un sitio de WordPress existente y mostrarlo en otro sitio.

Con el aumento de los marcos de JavaScript del lado del cliente como Angular, Backbone o Ember, ahora es posible utilizar uno de estos para crear experiencias de usuario enriquecidas al tiempo que se utiliza el back-end de WordPress.

Dicho esto, algunos posibles casos de uso para la API WP REST son:

  • Aplicaciones móviles
  • Paneles de administración personalizados para WordPress
  • Aplicaciones de una sola página (SPA)
  • Integración con otras plataformas del lado del servidor (como Ruby, .NET y Django, etc.)
  • y mucho más…

Realmente abre un nuevo mundo de posibilidades donde el único límite es la imaginación.

Una breve historia de las API de JSON REST en WordPress

Antes de las API REST basadas en JSON, la API utilizada para interactuar remotamente con WordPress era una API XML-RPC que todavía formaba parte del núcleo de WordPress. El problema con XML es que no es tan liviano como el formato JSON y su análisis no es eficiente. Atravesar XML también es un gran dolor de cabeza, mientras que atravesar un objeto JSON es tan fácil como manejar un objeto JavaScript nativo.

El primer plugin REST API que se presentó para WordPress fue JSON API que se lanzó en 2009. Fue construido en el Museo de Arte Moderno para su blog Inside / Out. El front end de este blog fue impulsado por Ruby on Rails, por lo que para recuperar publicaciones y agregar comentarios al back-end de WordPress, se desarrolló una API. Este complemento proporciona interfaces para recuperar contenido y enviar comentarios al backend de WP. Aunque no se actualizó durante más de dos años, este complemento todavía está presente en el repositorio oficial y está disponible.

Además del complemento API JSON, WordPress.com ya ha estado proporcionando API JSON a través del complemento JetPack.

La WP REST API, tal como la conocemos hoy, es un plugin de características que fue propuesto por Ryan McCue como parte de GsoC (Google Summer of Code) 2013. Aún debe incluirse (completamente) en el núcleo de WordPress en una versión futura. La versión actual 2.0 del complemento está en estado beta y se incluye parcialmente en el núcleo de WordPress en la versión 4.4. Es un proyecto impulsado por la comunidad dirigido por Ryan McCue y Rachel Baker. La página del repositorio oficial del complemento se encuentra en GitHub y la documentación oficial se puede encontrar en su sitio web.

Estado actual de la API REST WP

Como se mencionó anteriormente, la API WP REST se encuentra actualmente en estado de complemento y se está desarrollando activamente en GitHub. Se ha incluido parcialmente en el núcleo de WordPress en la versión 4.4 y Ryan ha descrito el plan en su propuesta de fusión en WordPress.org.

De acuerdo con la propuesta de fusión, la API de REST de WP se incorporaría en el núcleo de WP en dos etapas, tal como se describe a continuación:

Combinación de código de infraestructura

De acuerdo con la propuesta, en la etapa inicial, solo el código de nivel de infraestructura se fusionará con el núcleo de WP en la versión 4.4. Este código de infraestructura es la base real de la API REST de WP, ya que incluye serialización / deserialización JSON, vinculación, incrustación y, lo más importante, la capa de enrutamiento que impulsa la API. Este código no incluye los puntos finales y sus clases de controlador, pero proporciona una base para crear API dentro de WordPress.

En el momento de redactar este documento, este estado se ha completado y el código de infraestructura se ha fusionado en el núcleo de WordPress en la versión 4.4.

Combinación de Endpoints

Los puntos finales para publicaciones, páginas, usuarios y taxonomías, etc. se incorporarán en el núcleo de WP en la versión 4.5, es decir, una versión posterior a la combinación del código de infraestructura. Los puntos finales son los que hacen que la API sea útil para clientes generales. Incluyen mucha complejidad, incluida la asignación de los datos externos en formato JSON a los tipos de datos nativos de WordPress, y viceversa. Representan el código de dos tercios de la misma API con aproximadamente 5500 líneas.

La estrategia aquí es generar confianza entre los desarrolladores en la API proporcionando primero el código de la infraestructura en el núcleo. Esto permitiría a los desarrolladores de temas y complementos crear API personalizadas para incluirlas en sus temas y complementos. Pero como los puntos finales no se incluirán en esta etapa, esto limitaría la utilidad de la API inicialmente.

La brecha entre los dos lanzamientos le daría al equipo de compromiso del núcleo de WP el tiempo suficiente para revisar los endpoints API.

Otra ventaja que la API REST de WP aportaría a la comunidad de WordPress es el uso de GitHub en la versión que controla el proyecto. Dado que todas las contribuciones a WordPress se realizan a través de SVN y Trac, el equipo de la API REST de WP confía en mejorar el proceso de contribución al cerrar la brecha entre Trac y GitHub.

Después de la fusión de la API en el núcleo, podemos esperar ver desarrollos rápidos en otras áreas, incluida la autenticación OAuth 1.0a.

Herramientas

Para comenzar a probar con la API WP REST, necesitaremos un cliente HTTP que se utilizará para enviar solicitudes al servidor y ver la respuesta. Es realmente una cuestión de tu elección, pero usaré Postman para Google Chrome durante esta serie. Otras alternativas a Postman son:

Postman nos permite crear solicitudes HTTP rápidas de diferentes métodos, ver la respuesta del servidor y probar la configuración para la autenticación. Todas estas características serán extremadamente útiles cuando trabaje con la API WP REST.

Lo siguiente que debemos tener en nuestro servidor es WP-CLI. Con WP-CLI, podemos administrar remotamente nuestra instalación de WordPress desde la consola sin la necesidad de abrir la ventana del navegador. Tendremos que usar WP-CLI en la próxima parte de esta serie cuando configuremos la autenticación OAuth 1.0a. Puede encontrar las instrucciones de instalación en el sitio oficial.

Además de un cliente HTTP y WP-CLI, también necesitamos datos de demostración para nuestra instalación de WordPress. Sugiero revisar Theme Unit Test (XML) o el complemento Demo Data Creator que permite crear varias publicaciones, páginas y usuarios.

Instalando el complemento

En el momento de escribir este tutorial, la versión estable actual es 1.2.2 que se puede encontrar en el repositorio oficial. En esta serie, trabajaremos con la versión 2.0, ya que se ha reescrito desde cero y contiene muchos cambios importantes. Puede tomar la versión beta 2 desde su página de complemento oficial o desde su repositorio de GitHub.

Tenga en cuenta que no se recomienda instalar la versión beta actual en su entorno de producción. Configuré un entorno local de WordPress y te recomiendo que lo hagas para fines de desarrollo y pruebas.

Para instalar el complemento desde el repositorio de GitHub, abra su terminal y extraiga el complemento después de acceder a su directorio /wp-content/plugins/:

El complemento se descargará en el directorio /WP-API/.

Puede activarlo desde su administrador de WordPress para continuar con la prueba.

Para que funcione el complemento WP REST API, debes habilitar permalinks bonitos con WordPress. Aquí se supone que ya sabes realizar esta acción básica. Si no lo hace, no se preocupe ya que WordPress.org lo tiene cubierto.

Evaluar la disponibilidad de API

Después de que se haya instalado el complemento, podemos evaluar la disponibilidad de la API en nuestro servidor. No estamos limitados a usar la API en nuestro sitio solamente, de hecho, la usamos en cualquier sitio que la tenga instalada y habilitada. Para verificar la API en otros sitios, podemos enviar una solicitud HEAD al sitio de la siguiente manera usando su cliente HTTP:

Esto devolverá algo como lo siguiente en el encabezado de respuesta:

Response Header

El encabezado del enlace Link apunta a la ruta raíz de la API de WP, que en nuestro caso es la siguiente:

La API también se puede descubrir a través de JavaScript en el navegador (o jQuery) consultando el DOM para el elemento <link> apropiado como el siguiente:

Desde aquí podemos comenzar a recuperar el contenido del sitio a través de la API WP REST. Tenga en cuenta que solo las solicitudes autenticadas pueden editar o actualizar el contenido en el sitio y estoy guardando el asunto de configurar la autenticación para las próximas dos partes de esta serie.

¿Qué pasa después?

En esta parte introductoria de la serie aprendimos bastante sobre la arquitectura REST, la API WP REST y el propio HTTP. Primero analizamos conceptos básicos como qué es la arquitectura REST y cómo puede ayudar a los desarrolladores a crear mejores aplicaciones. Luego aprendimos sobre HTTP, sus verbos y tipos de respuesta. También miramos un breve historial sobre las API en WordPress y cómo la API WP REST es diferente de sus predecesoras.

En la parte final de este tutorial, instalamos el complemento de GitHub. Después de eso, nos familiarizamos con una solicitud HEAD que se puede utilizar para determinar la disponibilidad de la API en nuestro servidor y en otros servidores.

Después de haber configurado el entorno de trabajo básico, estamos listos para trabajar con las características que proporciona la API WP REST. En la próxima parte de la serie, buscaremos formas de configurar los métodos de autenticación compatibles con la API. Estos métodos de autenticación serán necesarios cuando se envíe una solicitud para recuperar, crear, actualizar o eliminar contenido. Así que estad atentos.


Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.