API: Visión general y configuración

1Introducción

En este tutorial, veremos cómo crear una API. Esto permitirá que servicios externos se conecten a un servicio de gestión de notas.

La API ofrece las siguientes funcionalidades:

  • Listar las notas del usuario.
  • Listar las etiquetas vinculadas a las notas.
  • Buscar notas usando criterios (etiqueta, fecha, título).
  • Recuperar el contenido de una nota personal.

2Configuración

Este desarrollo usa el plugin Api proporcionado por Temma. Como se indica en la documentación, el plugin debe añadirse al archivo de configuración, junto con la configuración de la conexión a la base de datos y la desactivación de las sesiones: 

<?php

return [
    'application' => [
        // configuración de la base de datos
        'dataSources' => [
            'db' => 'mysql://user:password@localhost/dbase'
        ],
        // desactivación de las sesiones
        'enableSessions' => false,
    ],
    // activación del plugin Api
    'plugins' => [
        '_pre' => [
            '\Temma\Plugins\Api',
        ],
    ],
];

Podrías pensar que habría que añadir una instrucción a la configuración para definir la vista JSON como vista por defecto. El plugin Api se encarga de esto.

Para gestionar la autenticación de los usuarios que se conectan a la API, el plugin usa un sistema de par de claves pública/privada. Los usuarios y las claves se almacenan en una base de datos. Consulta la documentación del plugin para conocer los detalles de las tablas que hay que crear.

3Rutas

La API propone un enfoque RPC, con una ruta para cada acción posible. Esto es más simple que el enfoque REST, en el que la misma ruta realiza acciones diferentes según el método HTTP usado para llamarla.

El plugin de la API gestiona las versiones de la API. Las URLs se prefijan por tanto con "/v1", para representar la primera versión de la API.

La API propondrá las siguientes URLs:

  • /v1/tag/list: Devuelve una lista de etiquetas.
  • /v1/note/list: Devuelve una lista de notas.
  • /v1/note/search: Busca notas según criterios.
  • /v1/note/get/[id]: Recupera el contenido de una nota.
  • /v1/note/add: Crea una nueva nota.
  • /v1/note/update/[id]: Modifica una nota.
  • /v1/note/remove/[id]: Elimina una nota.

Si la autenticación no es correcta, se devuelve un error HTTP 401.
Si un usuario autenticado intenta acceder a un recurso que no le pertenece, se devuelve un error HTTP 403.

3.1/v1/tag/list

Devuelve la lista de etiquetas usadas por las notas del usuario, con el número de notas correspondientes a cada etiqueta.

Ejemplo de retorno (formato JSON):

{
    "informática": 1,
    "web": 1,
    "cocina": 1
}

3.2/v1/note/list

Devuelve la lista de notas del usuario.

Ejemplo de retorno (formato JSON):

[
    {
        "id": 123,
        "title": "Sitios web interesantes",
        "tags": ["informática", "web"],
        "creation": "2024-01-01 12:00:00",
        "update": "2024-02-01 16:00:00"
    },
    {
        "id": 456,
        "title": "Cursos de cocina en línea",
        "tags": ["cocina", "web"],
        "creation": "2025-01-01 10:00:00",
        "update": "2025-01-01 10:00:00"
    }
]

Devuelve una lista de notas pertenecientes al usuario, obtenida a partir de criterios proporcionados en parámetros GET.

Parámetros posibles (todos opcionales):

  • tag (string): Etiqueta asociada a las notas.
  • title (string): Cadena a buscar en el título de las notas.

La respuesta es similar a la de la URL /note/list.

3.4/v1/note/get/[id]

Devuelve todos los datos de una nota cuyo identificador se pasa como parámetro en la URL.

Ejemplo de retorno (formato JSON):

{
    "id": 123,
    "title": "Sitios web interesantes",
    "tags": ["informática", "web"],
    "creation": "2024-01-01 12:00:00",
    "update": "2024-02-01 16:00:00",
    "content": "<p>Pequeña lista de sitios:</p>
<ul>
  <li><a href=\"https://www.temma.net/\">Temma</a></li>
</ul>"
}

Si la nota solicitada no pertenece al usuario, se devuelve un error HTTP 403.

3.5/v1/note/add

Crea una nueva nota, usando datos proporcionados en parámetros POST o GET.

Parámetros esperados (todos obligatorios):

  • title (string): Título de la nota.
  • tag (string | array): Etiqueta o lista de etiquetas a asociar con la nota.
  • content (string): Contenido de la nota en formato HTML.

Para proporcionar una lista de etiquetas, envía varios parámetros llamados tag[].

Esta URL devuelve el identificador de la nota creada.

3.6/v1/note/update/[id]

Actualiza los datos de la nota cuyo identificador se proporciona como parámetro en la URL.

La actualización usa los datos proporcionados como parámetro POST o GET. Cada parámetro es opcional, y un parámetro proporcionado sustituye el valor guardado.

Los parámetros posibles son:

  • title (string): Título de la nota.
  • tag (string | array): Etiqueta o lista de etiquetas a asociar con la nota.
  • content (string): Contenido de la nota en formato HTML.

Para proporcionar una lista de etiquetas, tienes que enviar varios parámetros llamados tag[].

Esta URL devuelve true en caso de éxito.

Si la nota solicitada no pertenece al usuario, se devuelve un error HTTP 403.

3.7/v1/note/remove/[id]

Elimina la nota cuyo identificador se proporciona como parámetro en la URL.

Esta URL devuelve true en caso de éxito.

Si la nota solicitada no pertenece al usuario, se devuelve un error HTTP 403.