Que es un API?
Un conjunto de metodos claramente definidos para comunicar varios componentes
Web API
- Debe ser agnostica
- Usa protocolos estandar http
- Una aplicacion web que quiere usar un api web
Estructura de un Request
Method URLHEADERS BODY
POST https://maryitsvapicourse.free.beeceptor.com/api/v1/order
200
579 ms
POST /api/v1/order HTTP/1.1
Content-Type: text/plain
User-Agent: PostmanRuntime/7.29.0
Accept: */*
Postman-Token: 98f692ca-28df-4964-a466-af587d73fd43
Host: maryitsvapicourse.free.beeceptor.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 115
{
"order": {
"orderDate":"21.01.2018",
"orderUser":"4",
"totalCost":"200"
}
}
Estructura de un Response
STATUS HEADERS BODY
HTTP/1.1 200 OK
Date: Mon, 04 Apr 2022 19:17:41 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Vary: Accept-Encoding
{ "status": "Awesome!"}
Actions
GET: retorna informacion de uno o varios recursos, recibe los parametros en la url
POST: agrega recursos, recibe los parametros en el body
PUT: actualiza los recursos, recibe los parametros en el body
DELETE: elimina los recursos, recibe los parametros en la url
PATCH: actualizacion de recursos parciales, similar a PUT
HEAD: similar a get pero sin body en la respuesta, sirve para hacer un precheckeo
OPTIONS: describe la disponibilidad de los verbos en una url.
Como crear una url de un servicio REST
- Debe explicarse por si sola
- Debe ser consistente en el API
- Debe ser predecible
- Incluir la palabra API
- Incluir el numero de la version
- Incluir el nombre de la entidad
- Incluir la subentidad si aplica
- Incluir los parametros si aplica
ejemplo:
https://www.myapp.com/api/v1/order/21/items?user=ana&date=21012018
Nombre del dominio
Puede tener la palabra api en el dominio o en la url ejemplos:
https://api.myapp.com
https://www.myapp.com/api
Nombre del producto(opcional)
Versionamiento
Si estamos usando versiones usar numeros naturales positivos, no usar flotantes, puede ir en la url, en los headers o como parametro en la url.
https://api.myapp.com/v1
https://www.myapp.com/api/v2
Entidad
Se trabaja con entidades o recursos
No usar nunca un verbo o nombres de metodos
Usar una sola palabra que se descriptiva
https://www.myapp.com/api/v2/order
Nota: que pasa si lo que queremos accederno es una entidad, o es una accion relacionada con una entidad? En ese caso podemos usar el verbo o el verbo y la entidad con la que se relaciona
https://api.spotify.com/v1/search?query
https://api.uber.com/v1.2/estimates/prices
Id parameter
Cuando estamos manipulando una entidad especifica se puede poner en la url, lo usamos con get put o delete
https://www.myapp.com/api/v2/order/21
Subentidades
Entidades que dependen de otras entidades, ejemplo Obtener los items de la orden 17
https://www.myapp.com/api/v2/order/21/items
Que no se debe hacer https://www.myapp.com/api/v1/itemsInOrder/17
Response code
GET
200 ok (por defecto)
400 bad request
401/ 403 no estan autorizados
404 no encontrado
POST
200 ok
201 creado (la entidad fue creada y retorna la entidad)
202 acceptado ( el request fue acceptado y esta siendo procesado, por ejemplo)
204 no content (el request fue completado pero no envia contenido de regreso)
400 bad request
401/ 403 no estan autorizados
404 no encontrado
PUT
200 ok
202 acceptado ( el request fue acceptado y esta siendo procesado, por ejemplo)204 no content (el request fue completado pero no envia contenido de regreso)
400 bad request
401/ 403 no estan autorizados
404 no encontrado
DELETE
200 ok
400 bad request401/ 403 no estan autorizados
404 no encontrado
Para los errores 4XX
400 Bad request
El cliente envio mal los datos, por ejemplo parametros invalidos o el json no es valido
rfc7807
hay un estandar de como se deben devolver los errores del api
{
"tipy":"validation-error",
"title":"parameters not valid",
"invalid-params":[
{
"name":"age",
"reason":"must be positive integer"
},
{
"name":"color",
"reason":"must be positive integer"
}
]
}
401 unauthorized
El cliente no esta autorizado a acceder la entidad
autorizacion es requerida
403 forbidden
El cliente no esta autorizado para acceder a la entidad
404 not found
El recurso que estamos buscando no fue encontrado
5XX Internal server error
Algo sucedio mientras se procesaba el request y no se completo el request
el cliente no puede hacer nada al respecto.
Es recomendado en caso de errores no controlados como este no dar pistas de que esta sucediendo al cliente.
Performance
Use operaciones asincronas
ejemplo in node js
para acceso a archivos, acceso a network, acceso a base de datos y operaciones que se demoren mucho es recomendable usar el async await
const fetch = require('node-fetch');
// dado que la funcion es asincrona se sigue ejecutando el codigo despues del llamado a la funcion
// sin embargo internamente el codigo espera a tener a res para continuar con data
async function asynajaxawait(){
const res = await fetch('https://api.github.com/users/KrunalLathiya')
const data = await res.json();
console.log(data.name);
}
asynajaxawait();
console.log("continue")
Use cache
Almacene los datos que son accedidos de manera frecuente cerca al api usualmente en memoria
asegurese de configurar la expiracion y la invalidacion
Rate limit
Limite el numero de request que puede procesar el api
cuando se supere el limite envie un codigo de error que indique que el servidor esta muy ocupado
pero que el servidor permanezca arriba
Quota
limite el numero de request que un cliente especifico puede hacer
ejemplo
10 queryes por segundo por ip
50.000 querys por proyecto
Monitoreo
Las herramientas de monitoreo te permiten ver problemas antes de que ocurran
o en caso de que ya hayan ocurrido te permiten revisar que paso.
Cual es el costo de un downtime?
Cuantos usuarios estan usando la aplicacion?
Que estan haciendo en la aplicacion?
Que monitorear
- Cuantos request por segundo tienen las apis?
# de fallos? - Latencia? el tiempo que toman un request en devolver los datos
- CPU? cuanto de cpu estamos usando?
- # de usuarios?
- # de sessiones?
- Cuanto de ram estamos usando?
Herramientas de monitoreo
Utilice una herramienta para monitorear sus APIS, ejemplo
azure service
application insight
add
availability
add test
configure the url
test every 5 minutes
success
validate the status code
Hateoas
cada rest devuelve todos los recursos que necesita
cada cliente no necesita tener mas conocimientos de otros recursos
ejemplo:
una lista de usuarios que tiene ordenes
el api de usuarios debe devolver todo los usuarios y las ordenes
https://netflix.github.io/genie/docs/3.0.0/rest/#_response_4
Bajo acoplamiento de servicios
Como evitar la telaraña de dependencias entre servicios
usar un directorio de paginas amarillas, se le pregunta al directorio cual es la url para que recurso (on premise)
usar un api gateway (cloud), usar un hombre en el medio, el servicio A le pregunta al gateway por un recurso y el gateway se lo da
Documentacion
Asegurese de hacer buena documentarion ejemplos swagger o open api
6 Design Rules Restfull
- Client - server: el cliente debe ser independiente del servidor, deben estar separados en distintos servicios
- Interfaz uniforme: uso contratos bien definidos, los metadatos deben ser descriptivos (host, content type, http status), las entidades deben ser claras en la url( /cars, /employee/12), links a las entidades adicionales que se necesitan HATEOAS, representacion del los recursos que retorna( car id=123, model=xs, make=BMW)
- Sin estado: el servidor no maneja el estado
- Cache: el servidor usa http headers para cachear respuestas
- Capas: cada capa debe ser independiente, ejemplo : capas: client app, load balancer, api reset, database
- Codigo bajo demanda:(opcional) el cliente puede enviar codigo para ser ejecutado en el servidor
Links que puedes usar
https://beeceptor.com/ crear api mock
https://petstore.swagger.io/#/pet/findPetsByStatus explorar api de ejemplo de swagger
https://swagger.io/tools/swagger-inspector/ generar documentacion usango el swagger inspector
https://www.postman.com/ probar el api
mi resumen de lo aprendido en https://www.udemy.com/course/rest-api-design-the-complete-guide/
