REST

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)

En algunos casos se puede usar el product nam, un agrupador de varias entidades

https://api.myapp.com/music/v1

 

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 request

401/ 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

Asegurese de establecer rate limit y cuota, si es posible use cache y asincronismo.

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/