API (application programming interface) es una pieza de software que comunica un cliente con los datos y servicios de otro, es decir, las APIs permiten comunicarse a dos piezas de software.
Ahora mismo, cuando alguien quiere construir una API, generalmente usa REST pero hay otros enfoques que según tu producto puede venir mejor.
Vamos a ver los diferentes tipos de APIs basándonos en el protocolo y en el tipo de datos que se usan para comunicarse:
- REST
- RPC
- SOAP
REST
REST (transferencia de estado representacional) es un tipo de arquitectura de desarrollo web que se apoya totalmente en el estándar HTTP.
Para que un API sea REST debe cumplir unos requisitos:
- No guarda estado entre peticiones.
-
Uso correcto de las URIs (uniform resource identifier).
- Uso correcto de HTTP
-
Hypermedia
Uso correcto de las URIs (uniform resource identifier).
Las URIs nos permiten identificar de forma única el recurso que queremos modificar, obtener o borrar. Existen varias reglas básicas para ponerle nombre a la URI de un recurso:
-
Los nombres de URI no deben implicar una acción, por lo tanto debe evitarse usar verbos en ellos.Ejemplo de URI incorrecta: /user/4/edit.Ejemplo de URI correcta: /user/4 y lo que queremos hacer se indica con el método HTTP como veremos más adelante.
- Deben ser únicas, no debemos tener más de una URI para identificar un mismo recurso.
-
Deben ser independiente de formato.Ejemplo de una URI incorrecta /user/4.pdf.
-
Deben mantener una jerarquía lógica.Ejemplo de una URI incorrecta: /user/4//1.ejemplo de una URI correcta: /organization/1/user/4
-
Los filtrados de información de un recurso no se hacen en la URI.Ejemplo de una URI incorrecta: /users/orden/desc y ejemplo de una URI correcta: /users?order=DESC
Uso correcto de HTTP
- Usar los métodos HTTP para indicar el tipo de acción que queremos realizar con el recurso.
- GET: Para consultar y leer recursos
- POST: Para crear recursos
- PUT: Para editar recursos
- DELETE: Para eliminar recursos.
- PATCH: Para editar partes concretas de un recurso.
-
Utilizar los códigos de respuesta nativos de HTTP (200,204,409,404…) para informar si la petición se ha realizado correctamente.
-
Ejemplo de respuesta incorrecta:
Status Code 200
Content:{
success: false,
code: 734,
error: "not enough data"
} -
Ejemplo de respuesta correcta:
Status Code 400
Content:{
message: "Invalid id" }
-
-
Tipos y formatos de contenido.REST es muy flexible y permite transmitir prácticamente cualquier tipo de datos, definiéndolo en el Header Content-Type, lo que nos permite mandar, XML, JSON, Binarios (imágenes, documentos), Text, etc.Sin embargo, el tipo de dato que se suele usar en las APIs suele JSON o XML.En REST generalmente se usa JSON, seguramente porque es interpretado de manera natural por JavaScript.
Hypermedia
Significa conectar mediante vínculos las aplicaciones clientes con las APIs, permitiendo a dichos clientes despreocuparse por conocer de antemano de cómo acceder a los recursos.
Es decir, cuando devolvemos por ejemplo una lista de usuarios indicaríamos la url para acceder a cada uno de ellos.
RPC
RPC (remote procedure call) es un protocolo que expone métodos para manipular datos a través del protocolo HTTP.
En RPC, los endpoints pueden contener verbos de la operación que realizan. Esto no está permitido en REST, que los endpoints solo contienen los recursos y la operación que queremos realizar se indica con los métodos de HTTP, como vimos arriba.
En RPC, sólo usa GET y POST: GET para obtener información y POST para todo lo demás.
El tipo de datos que se usa puede ser XML (XML-RPC) o JSON (JSON–RPC).
SOAP
SOAP (Simple Object Access Protocol) es un protocolo estándar que define cómo dos objetos en diferentes procesos pueden comunicarse por medio de intercambio de datos XML. No admite otros formatos a diferencia de REST.
Los servicios SOAP por lo general usan como protocolo de transporte HTTP que es lo más común cuando invocamos servicios web. Pero SOAP es agnóstico al protocolo de transporte, y puede enviar datos usando FTP, POP3, TCP, SMTP, Colas de mensajería (JMS, MQ, etc)…
Como hemos visto, XML-RPC y SOAP son protocolos muy similares, por ejemplo ambos usan XML para mandar datos. Se podría decir que XML-RPC es una subconjunto de la funcionalidad de SOAP. XML-RPC solo hace peticiones usando conexiones HTTP/S mientras que SOAP normalmente usa HTTP/S pero podría usar otro tipo de protocolos de transporte, como ya hemos visto.
Casos de uso
Para aclarar conceptos, vamos a ver un ejemplo de uso de una llamada en un API SOAP (JSON-RPC) y REST.
Ejemplo usando JSON-RPC:
POST /SendUserNotification
{"userId": 1, "message": "This is a RPC API!"}
y en REST, vemos como la llamada contiene el recurso que estamos manipulando:
POST /users/1/messages
{"message": "This is a REST API!!"
En REST deberíamos tener la certeza de que si hacemos:
GET /users/1/messages
un historial de estos mensajes es devuelto.
Entonces, ¿cuándo usar SOAP o REST?
Si lo que queremos es modelar el dominio, es decir modificar recursos (CRUD) entonces REST es una buena opción.
Pero si necesitamos realizar diversas acciones difíciles de diferenciar con los métodos HTTP, SOAP o RPC es mejor opción.
Vamos a verlo con un ejemplo para entenderlo mejor, imaginemos una app que tiene conversaciones y estas conversaciones necesitan ser empezadas, terminadas, interrumpidas o canceladas. Estas acciones son difíciles de implementar de manera clara por una API REST. En este caso, deberíamos usar un API basada en SOAP o RPC.
¿Tienes claro qué tipo de enfoque escoger cuando vayas a desarrollar una API?
