API CRUD

API

Hay varios tipos de API. Muchas API se utilizan para interactuar con una base de datos, de modo que podamos especificar la tabla solicitada y la fila solicitada dentro de nuestra consulta API y luego usar un método HTTP para realizar la operación necesaria. Por ejemplo, para el endpoint api.php de nuestro ejemplo, si quisiéramos actualizar la tabla en la base de datos city y la fila que actualizaremos tiene el nombre de ciudad london, entonces la URL se vería así:

curl -X PUT http://<SERVER_IP>:<PORT>/api.php/city/london ...SNIP...

CRUD

Como podemos ver, podemos especificar fácilmente la tabla y la fila en la que queremos realizar una operación a través de dichas API. Luego podemos utilizar diferentes métodos HTTP para realizar diferentes operaciones en esa fila. En general, las API realizan 4 operaciones principales en la entidad de base de datos solicitada:

Operación	Método HTTP	Descripción
Create	POST	Agrega los datos especificados a la tabla de la base de datos.
Read	GET	Lee la entidad especificada de la tabla de la base de datos.
Update	PUT	Actualiza los datos de la tabla de base de datos especificada.
Delete	DELETE	Elimina la fila especificada de la tabla de la base de datos.

Estas cuatro operaciones están vinculadas principalmente a las API CRUD comúnmente conocidas, pero el mismo principio también se utiliza en las API REST y en varios otros tipos de API. Por supuesto, no todas las API funcionan de la misma manera y el control de acceso de los usuarios limitará qué acciones podemos realizar y qué resultados podemos ver. El módulo Introducción a las aplicaciones web explica con más detalle estos conceptos, por lo que puede consultarlo para obtener más detalles sobre las API y su uso.

READ

Lo primero que haremos al interactuar con una API será leer datos. Como se mencionó anteriormente, podemos simplemente especificar el nombre de la tabla después de la API (p. ej. /city) y luego especificar nuestro término de búsqueda (p. ej. /london), de la siguiente manera:

Vemos que el resultado se envía como una cadena JSON. Para formatearlo correctamente en formato JSON, podemos canalizar la salida a la utilidad jq, que lo formateará correctamente. También silenciaremos cualquier salida de cURL innecesaria con -s, de la siguiente manera:

Gohanckz@htb[/htb]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/london | jq

[
  {
    "city_name": "London",
    "country_name": "(UK)"
  }
]

Como podemos ver, obtuvimos el resultado en un resultado muy bien formateado. También podemos proporcionar un término de búsqueda y obtener todos los resultados coincidentes:

Gohanckz@htb[/htb]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/le | jq

[
  {
    "city_name": "Leeds",
    "country_name": "(UK)"
  },
  {
    "city_name": "Dudley",
    "country_name": "(UK)"
  },
  {
    "city_name": "Leicester",
    "country_name": "(UK)"
  },
  ...SNIP...
]

Finalmente, podemos pasar una cadena vacía para recuperar todas las entradas de la tabla:

Gohanckz@htb[/htb]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/ | jq

[
  {
    "city_name": "London",
    "country_name": "(UK)"
  },
  {
    "city_name": "Birmingham",
    "country_name": "(UK)"
  },
  {
    "city_name": "Leeds",
    "country_name": "(UK)"
  },
  ...SNIP...
]

CREATE

Para agregar una nueva entrada, podemos usar una solicitud HTTP POST, que es bastante similar a lo que hemos realizado en la sección anterior. Simplemente podemos PUBLICAR nuestros datos JSON y se agregarán a la tabla. Como esta API utiliza datos JSON, también configuraremos el Header Content-Type en JSON, de la siguiente manera:

Gohanckz@htb[/htb]$ curl -X POST http://<SERVER_IP>:<PORT>/api.php/city/ -d '{"city_name":"HTB_City", "country_name":"HTB"}' -H 'Content-Type: application/json'

Ahora podemos leer el contenido de la ciudad que agregamos (HTB_City), para ver si se agregó exitosamente:

Gohanckz@htb[/htb]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/HTB_City | jq

[
  {
    "city_name": "HTB_City",
    "country_name": "HTB"
  }
]

Como podemos ver, se creó una nueva ciudad, que antes no existía.

UPDATE

Ahora que sabemos cómo leer y escribir entradas a través de API, comencemos a analizar otros dos métodos HTTP que no hemos usado hasta ahora: PUT y DELETE. Como se mencionó al principio de la sección, PUT se usa para actualizar las entradas de la API y modificar sus detalles, mientras que DELETE se usa para eliminar una entidad específica.

Nota: El método PATCH HTTP también se puede utilizar para actualizar entradas de API en lugar de PUT. Para ser precisos, PATCH se usa para actualizar parcialmente una entrada (solo modificar algunos de sus datos “por ejemplo, solo nombre_ciudad”), mientras que PUT se usa para actualizar la entrada completa. También podemos usar el método OPTIONS HTTP para ver cuál de los dos es aceptado por el servidor y luego usar el método apropiado en consecuencia. En esta sección nos centraremos en el método PUT, aunque su uso es bastante similar.

El uso PUT es bastante similar a POST este caso, con la única diferencia de que tenemos que especificar el nombre de la entidad que queremos editar en la URL; de lo contrario, la API no sabrá qué entidad editar. Entonces, todo lo que tenemos que hacer es especificar el citynombre en la URL, cambiar el método de solicitud a PUT y proporcionar los datos JSON como lo hicimos con POST, de la siguiente manera:

Gohanckz@htb[/htb]$ curl -X PUT http://<SERVER_IP>:<PORT>/api.php/city/london -d '{"city_name":"New_HTB_City", "country_name":"HTB"}' -H 'Content-Type: application/json'

Vemos en el ejemplo anterior que primero especificamos /city/london como nuestra ciudad y pasamos una cadena JSON contenida “city_name”:”New_HTB_City” en los datos de la solicitud. Entonces, la ciudad de Londres ya no debería existir y New_HTB_City debería existir una nueva ciudad con ese nombre. Intentemos leer ambos para confirmar:

Gohanckz@htb[/htb]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/london | jq

Gohanckz@htb[/htb]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/New_HTB_City | jq

[
  {
    "city_name": "New_HTB_City",
    "country_name": "HTB"
  }
]

De hecho, reemplazamos con éxito el nombre de la ciudad antigua por el de la nueva ciudad.

Nota: En algunas API, la operación Update también se puede utilizar para crear nuevas entradas. Básicamente enviaríamos nuestros datos, y si no existen los crearía. Por ejemplo, en el ejemplo anterior, incluso si no existiera una entrada con una ciudad london, se crearía una nueva entrada con los detalles que pasamos. En nuestro ejemplo, sin embargo, este no es el caso. Intente actualizar una ciudad que no existe y vea qué obtendrá.

DELETE

Finalmente, intentemos eliminar una ciudad, lo cual es tan fácil como leer una ciudad. Simplemente especificamos el nombre de la ciudad para la API y usamos el método DELETE HTTP, y eliminaremos la entrada, de la siguiente manera:

Gohanckz@htb[/htb]$ curl -X DELETE http://<SERVER_IP>:<PORT>/api.php/city/New_HTB_City

Gohanckz@htb[/htb]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/New_HTB_City | jq
[]

Como podemos ver, después de eliminar New_HTB_City, obtenemos una matriz vacía cuando intentamos leerla, lo que significa que ya no existe.