En este Artículo te voy a explicar sobre que trata una REST API y algunas mejores Prácticas que debes considerar cuando estés creando un Proyecto con esta tecnologías, la cual es muy usada por grandes empresas y Proyectos para agilizar y facilitar el accesos dinámico de los usuarios a sus Productos, vamos con este Post.
Primero haremos una introducción sobre API REST y varios detalles, luego expondré algunas buenas Practicas para trabajar con esta tecnología.
Que es una API REST ?
El término API es el acrónimo de Application Programming Interface que traducido al español significa Interfaz de Programación de Aplicaciones, asimismo REST son las iniciales de Representation State Transfer y traducido al español significan Transferencia de Estado Representacional.
API REST es un estilo de arquitectura de Software que permite consumir datos o usar una determinada funcionalidad de un Servicio o Producto alojado en Servidores Informáticos haciendo uso de rutas especificas, por ejemplo un Desarrollador puede usar las siguientes rutas para hacer Login, Registro y Mostrar los Postres o Datos almacenados en el servidor
|
1 2 3 4 5 6 7 8 9 10 |
// Login https://undominio.com/api/v1/tiendadepostres/login // Registro https://undominio.com/api/v1/tiendadepostres/registro // Leer Postres https://undominio.com/api/v1/tiendadepostres/postres |
Los Desarrolladores y Empresas suelen consumir diferentes APIs en sus proyectos, cada una brinda una funcionalidad o tarea independiente.
Una API REST puede contener muchas rutas, estas son creadas por un Desarrollador que cuente con conocimientos sobre Lenguajes de Servidor (Backend), como Python, Ruby, Node JS, PHP, etc.
Grandes empresas como Facebook, Netflix, Google entre otras, utilizan la Arquitectura API REST para la mayoría de sus Productos o Servicios, por ejemplo Facebook brinda en su Documentación para Desarrolladores una ruta en donde se pueden enviar los mensajes mediante el método POST, esta ruta pide que se incluya en ella el PAGE_ACCES_TOKEN por Seguridad, este token se obtiene desde la misma Plataforma al crear un nuevo Proyecto en Facebook for Developers
|
1 2 3 4 |
// Todos los mensajes se envían enviando una solicitud POST a la API de envío con su token de acceso a la página adjunto a la cadena de consulta de URL: https://graph.facebook.com/v5.0/me/messages?access_token=<PAGE_ACCESS_TOKEN> |
Cada empresa maneja sus propias rutas de API REST, al acceder a una ruta, esta lleva acabo la tarea correspondiente que el Desarrollador que la creo le ha especificado.
Para acceder a las rutas de un API REST se necesita utilizar un cliente como una Navegador, Dispositivo Móvil, etc.
RESTful API
Este término deriva de API REST y es un estado en donde este cuenta con ciertas características que lo hacen más completo, haciendo uso de ciertas reglas, protocolos HTTP y recursos determinados:
- Arquitectura Cliente – Servidor: Esta conformado por el Cliente (Frontend) el cual es usado para usar una ruta de la API REST y el Servidor (Backend) el cual procesa las solicitudes que el Cliente hace al acceder a una ruta.
- Sin estado (Stateless): El Servidor en donde esta alojado el código no debe guardar ningun estado de las distintas solicitudes que hace un Cliente, el estado de la sesión queda exclusivamente a cargo del cliente.
- Caché (Cacheable): El Cliente que hace uso de las rutas de API REST debe poder almacenar las respuestas en un caché para un mejor rendimiento.
Un API REST profesional debe de ser RESTful API porque adopta recursos importantes, los que mencione principalmente y otras buenas Prácticas que te compartiré a continuación.
Mejores Prácticas de API REST
Vamos a ver algunos puntos importantes en cuanto a buenas prácticas que hará que las APIs brillen y facilite de buena manera a los usuarios Desarrolladores que hagan uso de ellas
APIs con rutas Concretas
Cuando creamos un Software, normalmente usamos la abstracción y poliformismo para acceder a los recursos de nuestras APIs, siempre buscamos reutilizar la mayor cantidad de código posible, entonces deberíamos escribir nuestras APIs de esta manera también ?
Bueno, ese no es exactamente el caso con las API REST, es mejor hacer rutas Concretas y Definidas, por ejemplo a continuación tenemos 2 versiones de una ruta de API REST para acceder a los datos de un Blog
Versión 1
|
1 2 3 |
/entidades |
Versión 2
|
1 2 3 4 5 |
/autores /blogs /bloposts |
La versión ideal es la 2, ya que tiene rutas mas concretas, cada una para solicitar un determinado recurso sin afectar los demás datos.
URI con Formato Sencillos
Debemos de hacer las rutas lo más sencillas posible, siempre en minúsculas, en algunos casos se debe evitar los siguientes casos
No hacer:
|
1 2 3 4 5 6 7 8 |
/listarPostsBlog /actualizarPostBlog/11 /eliminarPostBlog/11 /obtenerAutor/4 /eliminarAutor/4 /actualizarAutor/4 |
Si hacer:
|
1 2 3 4 5 6 7 8 |
/postsblog/listar /postsblog/actualizar/11 /postsblog/eliminar/11 /obtener/autor/4 /eliminar/autor/4 /actualizar/autor/4 |
La segunda manera de crear las rutas de un API REST es más limpio y sencillo para el usuario final, si deseas puedes hacerlo más limpio, esto depende de ti.
Manejo de Errores
Este aspecto es muy importante en la creación de un API REST, guiémonos de las populares aplicaciones, por ejemplo la API de la aplicación Twitter arroja el siguiente error en formato JSON al acceder a la siguiente ruta
Ruta:
|
1 2 3 |
GET https://api.twitter.com/1.1/account/settings.json |
Error:
|
1 2 3 4 5 6 7 8 9 10 |
{ "errors":[ { "code":215, "message":"Bad Authentication data." } ] } |
Puedes ver que arroja un error de Autenticación incorrecta, Twitter proporciona un código de Estado con una breve descripción explicando lo que ocurrió y nos deja brindan una Página con los Códigos de respuesta de su API, para saber que sucede en cada código.
Entonces tu API REST debe contar con estos códigos y una guía para el usuario final, de esta manera no se complicará durante el uso de la API REST.
Códigos de Estado
Las rutas de API REST utilizan un Código de estado HTTP, cada código es un estado que describen múltiples respuestas posibles, es importante que apliques estos códigos de estado para que el usuario final tenga conocimiento sobre el estado de una determinada acción, los Desarrolladores están familiarizados con los siguiente códigos de estado
|
1 2 3 4 5 |
200 OK 400 Bad Request 500 Internal Server Error |
Si inicias con estos 3 códigos de estado, puedes cubrir la mayoría de funcionalidades en tu API REST, existen otros códigos de Errores como:
|
1 2 3 4 5 6 7 |
201 Created 204 No Content 401 Unauthorized 403 Forbidden 404 Not Found |
Te recomiendo leer el artículo Aprende los Códigos de Errores al hacer peticiones HTTP al servidor, en donde explico que significa cada código de estado.
Entonces puedes ayudar al usuario que consume una ruta de tu API REST mostrandole el error que esta sucediendo mientras este esta accediendo a una ruta, este error se lo puedes mostrar mediante un Código de Estado, por ejemplo en Laravel Framework podemos devolverle al usuario un código 401 que significa que el usuario no esta autorizado a usar dicho recurso, en este caso la ruta /listarpostres
|
1 2 3 4 5 6 7 8 |
public function listarpostres() { $data = array(); return response()->view('layouts.default', $data)->setStatusCode(404); } |
De esta manera el usuario tendrá conocimiento de lo que esta pasando y tomará rápidamente la acción adecuada.
Seguridad
Ni siquiera dudarlo, la seguridad es parte importante en un API REST, esta usa mecanismos y protocolos HTTP que pueden ser vulnerables, una forma de proteger el acceso a las rutas de usuarios maliciosos es usando Tokens de Seguridad, las grandes empresas usan este tipo de Seguridad, por ejemplo puedes pedir que el usuario pase un token en las rutas de tu API REST
|
1 2 3 4 |
// Leer Postres https://undominio.com/api/v1/tiendadepostres/postres?token=AadsdDADQEE345sfsfd34343D |
Te dejo un tutorial en donde hago uso de JWT (JSON Web Tokens) una herramienta de Seguridad que hace uso de Tokens para que tengas una idea sobre la seguridad con Tokens:
Si mantienes la Seguridad de tu API REST, tendrás clientes más satisfechos y tus datos estarán a salvo.
Versión de API REST
Una vez que terminaste de crear la primera versión de tu API REST y ha tenido éxito, muchas personas lo usan y están satisfechos con ella, pero siempre vas a querer agregar una nueva y tentativa funcionalidad, al implementarla puede romper otras partes del sistema o un cambio a última hora.
Puedes manejar las versiones de API REST en las rutas correspondientes, por ejemplo la primera versión va tener en la ruta la expresión /v1/ para indicar que se trata de la Primera versión
|
1 2 3 4 5 6 7 8 9 10 |
// Login https://undominio.com/api/v1/tiendadepostres/login // Registro https://undominio.com/api/v1/tiendadepostres/registro // Leer Postres https://undominio.com/api/v1/tiendadepostres/postres |
Y si lanzas la Segunda versión pues igualmente agrega en la ruta la expresión /v2/
|
1 2 3 4 5 6 7 8 9 10 |
// Login https://undominio.com/api/v2/tiendadepostres/login // Registro https://undominio.com/api/v2/tiendadepostres/registro // Leer Postres https://undominio.com/api/v2/tiendadepostres/postres |
Documentación
Si tu aplicación que cuenta con la Arquitectura API REST y va ser Publica en versión Free o de Pago, debes de ofrecerle una documentación adecuada a los usuarios que la van a usar, sin documentación tu API REST es tan buena como muerta.
Esta puede ayudar al usuario a ser coherente, usando una sintaxis clara y descriptiva en el uso de las rutas y demás recursos del API REST, algunas empresas ofrecen esta documentación a los usuarios finales
Twilio: https://www.twilio.com/docs/api/rest/
Facebook: https://developers.facebook.com/docs/
Google Maps: https://developers.google.com/maps/documentation/
Es por eso que sus API REST tienen gran popularidad en el medio.
Conclusión
Ya sabes sobre que trata un API REST y algunas de las Buenas Prácticas que debes seguir al crear una, conforme vayas creando tu propia API REST, vas a darte cuenta que hay otros aspectos que necesitas resolver y hacer crecerlo.
La Mayoría de rutas en un API REST devuelven datos en formato JSON, te recomiendo leer el artículo Tipos de Datos que podemos usar en JSON para que estés familiarizado con los datos que aparecen en los datos del JSON de la ruta respectiva.
Nota (s)
- En un futuro la herramienta JWT (JSON Web Tokens) puede dejar de existir, ser modificada o continuar, esto no depende de nosotros si no de los Desarrolladores que dan soporte a esta herramienta.
- No olvides que debemos utilizar la tecnología para hacer cosas buenas por el mundo.
Síguenos en las Redes Sociales para que no te pierdas nuestros próximos contenidos.