/notes-apis

Notas sobre APIs

MIT LicenseMIT

Notas sobre APIs

👉 Ver todas las notas

Contenido

API

Application Programming Interface), define una interfaz con ciertas operaciones, que nos permiten interactuar con una aplicaciĂłn hosteada en un servidor.

Nos permite agregar una barrera de seguridad: el cliente no puede acceder directamente a la DB sino a través de la API.

Una API expone datos y diferentes tipos de acciones que podemos realizar, a través de los endpoints, por ejemplo

  • InformaciĂłn disponible
  • Servicios
  • Parámetros
  • Formato de la respuesta

Una API forma parte del backend de una aplicaciĂłn y es independiente de los lenguajes y plataformas que utilicemos.

↑ Ir al inicio

Listas de APIs web disponibles para utilizar

↑ Ir al inicio

REST

REST (Representational State Transfer) es una convenciĂłn para desarrollar servicios web (APIs), basados en el protocolo HTTP. Vamos a llamar APIs REST a las APIs que desarrollemos siguiendo estas convenciones.

↑ Ir al inicio

Propiedades de una API REST

  • Utilizamos URLs para definir recursos
  • JSON como formato de intercambio
  • Acciones basadas en los verbos HTTP (utilizamos el protocolo HTTP para transferir datos)
  • Uso de los status HTTP (200 - ok, 404 - resource not found, 500 - server error, etc)
  • Stateless: los datos del cliente no se almacenan en el servidor entre requests. Cada request contiene toda la info necesaria para ser ejecutada, por lo que que ni el cliente ni el servidor necesitan recordar ningĂşn estado previo.
  • Arquitectura cliente<->servidor: hay una separaciĂłn de responsabilidades entre el frontend (cliente) y el backend (server). Operan de forma independiente entre sĂ­ y ambos pueden ser reemplazados.
  • Cache: la data que proviene del server puede ser cacheada en el cliente, lo cual nos permite obtener mejoras de performance.
  • Sistema de capas: el cliente no necesita saber si está interactuando directamente con un servidor, proxy, load balancer, etc.
  • Interfaz uniforme cada recurso del servicio REST debe tener una Ăşnica direcciĂłn, "URI", que simplifica la interacciĂłn entre el cliente y el servidor.

👉 Ver más detalles en Core Principles of RESTful API

↑ Ir al inicio

CRUD

Una API REST nos permite desarrollar servicios para crear, leer, actualizar o eliminar datos, conocidos como CRUD operations por sus siglas en inglés (Create, Read, Update, Delete).

↑ Ir al inicio

API Key

Sirve para identificar al usuario/cliente que está realizando el request. Generalmente se utiliza para aplicar rate limiting (limitar los recursos del servidor que podemos consumir de forma gratuita, por ejemplo bloqueando los requests después de cierta cantidad).

Para más info, ver Use Web APIs.

↑ Ir al inicio

Endpoint

Un endpoint de una API REST expone un recurso o una colección de recursos para que sean consumidos. Un endpoint incluye el tipo de acción (request) a realizar con el recurso (o la colección), la ruta y los parámetros necesarios. El tipo de acción está basado en los verbos HTTP (GET, POST, PUT, DELETE, etc). Por ejemplo

Los endpoints que definamos tienen que resolver el siguiente problema: proveer una forma uniforme de identificar los recursos disponibles (interfaz uniforme)

↑ Ir al inicio

Ejemplos

Request 1

GET /api/customers

Response 1

[
 { "id": 1, "name": ...},
 { "id": 2, "name": ...},
 ...
]

Request 2

GET /api/customers/7

Response 2

{ "id": 7, "name": ...}

Endpoints

GET /api/customers
GET /api/customers/7
POST /api/customers
PUT /api/customers/1
DELETE /api/customers/2

↑ Ir al inicio

Verbos HTTP

  • GET: Leer data de un recurso existente, sin modificarlo.
  • POST: Crear un nuevo recurso en el server, usando la info enviada en el payload del request. Por convenciĂłn, cuando creamos un nuevo recurso, debemos retornar el objeto que lo representa en el response.
  • PUT: Actualizar un recurso existente, usando la info enviada en el payload del request. En el caso de que el recurso no exista, lo crea.
  • DELETE: Eliminar un recurso existente.

↑ Ir al inicio

HTTP Status Codes

Ver httpstatuses.com

↑ Ir al inicio

path params vs query params en una API REST

Ver When do I use path params vs. query params in a RESTful API?

↑ Ir al inicio

Ejercicio

Vamos a crear una API REST con Express. La misma tendrá información sobre películas, almacenada en un array.

El formato de las películas será el siguiente:

movie = {
  "id": 1,
  "title": "Back to the Future",
  "year": 1985,
  "genre": "Science Fiction"
}
  • Acá hay ejemplos de pelĂ­culas para usar y acá tenĂ©s un JSON con muchas más.
  • El array de pelĂ­culas estará inicialmente vacĂ­o. Se recomienda utilizar un mĂłdulo aparte para el array (importarlo donde sea necesario) y definirle una API para interactuar con el mismo (ejemplo, si el array se llama movies, definir la operaciĂłn movies.add para agregar una nueva pelĂ­cula, etc)
  • El id se calcula al agregar una nueva pelĂ­cula (no forma parte del payload del request), segĂşn el orden (la primera tendrá id=1, la segunda id=2, etc).
  • Utilizar el Router de Express para definir la lĂłgica de routing en un mĂłdulo aparte, y setear /api como prefijo de todas las rutas. Utilizar el mĂ©todo route(), para definir las rutas de una forma más declarativa.
  • Utilizar nodemon para desarrollar.
  • En caso de necesitar debuggear la aplicaciĂłn, utilizar esta guĂ­a.

API Endpoints

  • GET /api/movies: retorna el array de pelĂ­culas, en formato JSON.
  • GET /api/movies/:id: retorna la pelĂ­cula con el id correspondiente, en formato JSON. En el caso de que no exista, generar el error "404 - The movie with the id {ID} was not found" (donde ID es el parámetro utilizado) con status code 404 y pasarle el objeto err a next.
  • POST /api/movies: agrega una nueva pelĂ­cula, con la info especificada más arriba. Validar el body del request como se indica más abajo. Si es inválido, generar el error "400 - Bad Request" y pasarle el objeto err a next, sino, agregar la pelĂ­cula correspondiente y retornar la info de la misma en el response.
  • PUT /api/movies/:id: actualiza la info de una pelĂ­cula (title Ăł year, el id no puede editarse). Para esto, primero debe buscarla por el id y si no existe, debe agregar la nueva pelĂ­cula, con el id correspondiente.
  • DELETE /api/movies/:id: elimina la pelĂ­cula con el id correspondiente. Para esto, primero debe buscarla por el id, si no existe, generar el error "404 - The movie with the id {ID} was not found" (donde ID es el parámetro utilizado), y un status code 404 y pasarle el objeto err a next.
  • GET /api/movies/genres: retorna la lista de gĂ©neros (sin repetir), correspondientes a las pelĂ­culas que tengamos
  • GET /api/movies/years: retorna la lista de años (sin repetir), correspondientes a las pelĂ­culas que tengamos

Query strings

  • Si se utiliza el query string ?year= con GET /api/movies, debe retornarse la lista de pelĂ­culas correspondientes a ese año, en formato JSON.
  • Si se utiliza el query string ?genre= con GET /api/movies, debe retornarse la lista de pelĂ­culas correspondientes a ese gĂ©nero, en formato JSON.
  • Si se utilizan los query strings ?sortBy=title Ăł ?sortBy=year con el endpoint GET /api/movies, debe retornarse la lista de pelĂ­culas ordenada por año Ăł nombre de forma ascendente, respectivamente.

En ambos casos, si no hay pelĂ­culas para mostrar, debe retornarse el array vacĂ­o [] (siempre como JSON).

Validaciones

Utilizar el middleware express-validator para realizar las siguientes validaciones sobre el input (body del request)

  • title: debe existir y tener al menos 2 caracteres, sino generar el error movie title is required and should have minimum 2 characters., con status code 400 y pasarle el objeto err a next.
  • year: debe ser un valor numĂ©rico entre 1800 y 2020, sino generar el error movie year is required and should be a number between 1800 and 2020., con status code 400 y pasarle el objeto err a next.

Middleware a utilizar

↑ Ir al inicio