Primeros pasos con la API

¿Qué es?

Nuestra API REST te permite ver, crear o editar contenido en cualquier sitio de WordPress.com y en cualquier sitio autoalojado (WordPress.org) conectado a través de Jetpack. Esto no solo incluye entradas de blog y páginas, sino también comentarios, etiquetas, categorías, archivos multimedia, estadísticas del sitio, notificaciones, configuración de compartir, perfiles de usuario y muchas otras funciones de WordPress.com.

Algunas solicitudes (como, por ejemplo, listas de entradas públicas) no necesitan ser autenticadas, pero cualquier acción que requiera que un usuario esté conectado (como crear una entrada) requiere un token de autenticación. Para hacer solicitudes autenticadas, tendrás que crear una cuenta de WordPress.com (si todavía no la tienes). También tendrás que crear una aplicación cliente de WordPress.com.

¿Cómo se utiliza?

Hay dos formas de explorar las funciones de la API: a través de la documentación o en la consola de desarrollo. La documentación (developer.wordpress.com/es/docs/api/) enumera todos los endpoints disponibles y detalla el input y el output de cada uno, junto con código de ejemplo en curl y PHP. La consola de desarrollo (developer.wordpress.com/docs/api/console/) te permite crear y probar solicitudes reales de la API.

Hacer solicitudes no autenticadas es muy sencillo. Como no se necesita ningún cabecera especial, puedes incluso abrir este enlace en el navegador para ver el resultado: https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/?number=2&pretty=true

Hacer solicitudes autenticadas requiere algunos pasos más. (Si ya conoces bien OAuth2, puedes leer directamente la documentación técnica).

Utilizamos el protocolo OAuth2, que es simplemente una forma de que tu aplicación actúe en nombre de un usuario. Por eso necesitas crear una aplicación cliente, incluso para aplicaciones de un solo usuario: el cliente sirve de puente entre cualquier usuario de WordPress.com y nuestra API. Para una aplicación de un solo usuario puede ser un poco confuso, porque en este caso tú eres tanto el cliente como el usuario que está iniciando sesión. Sin embargo, un cliente puede adquirir tokens para muchos usuarios, de la misma forma que el portero de un edificio tiene las llaves de muchas puertas diferentes.

Una de las características de OAuth es el uso de tokens o cadenas que actúan como una especie de clave. Representan el consentimiento del usuario para actuar en su nombre. Esto tiene varias ventajas: las aplicaciones cliente no tienen que solicitar o almacenar las contraseñas de los usuarios, y los tokens pueden caducar o ser revocados por cliente. A diferencia de una combinación de nombre de usuario + contraseña, que se puede usar en muchos lugares, los tokens solo pueden ser utilizados por el cliente que los solicitó.

Si alguna vez has iniciado sesión en una web usando Facebook o X, has visto cómo funciona OAuth. La parte interesante es la forma en que te envía a Facebook, pidiéndole a Facebook que inicie sesión y permita el acceso. Piénsalo como si fuera una conversación entre tres interlocutores:

Usuario: «Me gustaría hacer una entrada a través de este cliente API».
Cliente: «Muy bien. Oye, WordPress.com, quiero hacer algo en nombre de este usuario. ¿Puedes preguntarle si está de acuerdo?».
WordPress.com: «Claro. Oye, usuario, ¿te parece bien que el cliente actúe en tu nombre?».
Usuario: «Sí, no hay problema. Confío en este cliente para que realice acciones por mí en el futuro».
WordPress.com: «Perfecto. Cliente, aquí tienes un token que te permitirá tomar acciones por este usuario. Cuídalo bien».
(Más tarde)
Cliente: «Hola, WordPress.com. Estoy haciendo una entrada en nombre de un usuario en particular. Estos son todos los detalles sobre la publicación, y para acompañarlo, aquí está el token que muestra que tengo permiso para publicar como este usuario».

¿Y cómo funciona esto desde la perspectiva del cliente? Lo primero que tienes que hacer es enviar al usuario a WordPress.com para solicitar acceso. Los enlazarás a una URL específica que incluye, lo más importante, tu ID de cliente y una URL de redirección. La ID de cliente nos dice qué cliente está haciendo la solicitud; la URL de redirección es a donde enviaremos al usuario de vuelta. Como medida de seguridad, también pedimos que la URL de redirección esté definida en los ajustes de tu aplicación. Si la que pasas no coincide con la que está en los ajustes, no se podrá completar la solicitud.

Cuando el usuario autoriza la solicitud, lo enviaremos de vuelta a la URL de redirección, pero con un extra: el token se añadirá al final. Tu aplicación debería estar preparada para gestionar esa URL, extrayendo los tokens entrantes para guardarlos y usarlos más adelante.

Una vez que tengas el token, puedes autenticar cualquier solicitud de API incluyéndolo en las cabeceras de la solicitud. Esto se hace incluyendo una cabecera llamada «Authorization» con el valor «BEARER your_token_here».

Ahora que entiendes lo básico del proceso de autenticación, consulta la documentación de OAuth2 para ver información más técnica, incluyendo ejemplos de código.

Próximos pasos

La documentación completa es una buena forma de explorar todas las funciones de la API. También puedes echarle un vistazo a nuestras aplicaciones de ejemplo o familiarizarte con la consola de desarrollo.

¿No tienes claro por dónde empezar? Estos son algunos endpoints interesantes:

• GET /sites/$site/posts: Consigue una lista de entradas de un sitio. Por ejemplo, las últimas entradas destacadas en discover.wordpress.com:
  
  https://public-api.wordpress.com/rest/v1.1/sites/discover.wordpress.com/posts/?number=2&pretty=true
• GET /read/tags/$tag/posts: Consigue una lista de entradas con una etiqueta concreta. Por ejemplo, entradas recientes sobre gatos:
  
  https://public-api.wordpress.com/rest/v1.1/read/tags/cats/posts?number=2&pretty=true
• GET /sites/$site/stats/top-posts: Visualiza las entradas principales de tu sitio (requiere autenticación).
• GET /read/recommendations/mine: Consigue una lista de recomendaciones de blogs basadas en blogs que ya sigues (requiere autenticación).
• POST /sites/$site/posts/new: Crea una nueva entrada (requiere autenticación).

¿Alguna duda o comentario? ¿Te gustaría contarnos lo que has creado con nuestra API? Ponte en contacto con nosotros.