Buenas prácticas para desarrollo API RESTful – Parte 1

En este artículo hablaremos de Restful, más específicamente de las buenas prácticas para desarrollo de una Restful API.

Si eres desarrollador o te dedicas a algún trabajo relacionado a las tecnologías de la información de seguro que conoces los servicios web o por lo menos has escuchado hablar de ellos.

 ¿Porque una RESTful API?

Facebook, Google, Github, Netflix y algunos otros gigantes tecnológicos han dado una oportunidad a los desarrolladores y productos para consumir sus datos a través de API. Esto con el fin de integrar sus datos con aplicaciones de sus clientes.

Entonces si tu objetivo es integrar múltiples fuentes de información, Restful es una de las mejores opciones disponibles.

Pero hacerlo de manera desordenada sin ningún control sobre su estructura y las particularidades del mismo sería realmente desastroso.

La API es como un artista que actúa en el escenario, y sus usuarios son la audiencia.

Terminologías

Las siguientes terminologías son las más importantes:

• Resource es un objeto o representación de algo, que tiene algunos datos asociados con él y puede haber un conjunto de métodos para operar en él. P.ej. Los animales, las escuelas y los empleados son recursos y eliminar, agregar, actualizar son las operaciones que se realizarán en estos recursos.
• Los Collections son un conjunto de recursos, por ejemplo, Empresas es la colección de recursos de la Empresa.
• URL (Uniform Resource Locator) es una ruta a través de la cual se puede ubicar un recurso y se pueden realizar algunas acciones en él.

API EndPoint

Supongamos el caso práctico de una empresa que tiene empleados, y lo que se quiere es realizar unos servicios Restful que nos permita trabajar con los datos de los empleados, tendríamos lo siguiente:

• /addNewEmployee
• /updateEmployee
• /deleteEmployee
• /deleteAllEmployees
• /promoteEmployee
• /promoteAllEmployees

¿Que está mal?, la URL solo debe contener recursos (sustantivos), no acciones o verbos. La ruta de la API /addNewEmployee contiene la acción addNew junto con el nombre de recurso Employee.

Entonces, ¿cuál es la forma correcta?
El EndPoint de /companies es un buen ejemplo, que no contiene ninguna acción. Pero la pregunta es ¿cómo le decimos al servidor sobre las acciones que se realizarán en los recursos de las empresas, a saber, ya sea para agregar, eliminar o actualizar algún empleado?

Aquí es donde los métodos HTTP (GET, POST, DELETE, PUT), también llamados verbos, desempeñan la funcionalidad requerida.

El recurso siempre debe ser plural en el punto final de la API y si queremos acceder a una instancia del recurso, siempre podemos pasar el ID en la URL.

• El método GET <path>/companies deben obtener la lista de todas las empresas
• El método GET <path>/companies/34 debe obtener el detalle de la empresa 34
• El método DELETE <path>/companies/34 debería eliminar la empresa 34

En algunos otros casos de uso, si tenemos recursos en un recurso, por ejemplo, empleados de una empresa, algunos de los EndPoints de API de ejemplo serían:

• GET /companies/3/employes/ debería obtener la lista de todos los empleados de la empresa 3
• GET /companies/3/employes/45 debe obtener los detalles del empleado 45, que pertenece a la compañía 3
• POST /companies debe crear una nueva empresa y devolver los detalles de la nueva empresa creada
• DELETE /companies/3/employes/45 debería eliminar al empleado 45, que pertenece a la empresa 3

¿No son las API ahora más precisas y consistentes?

Conclusión

Como hemos podido ver tener una API bien desarrollada con buenas prácticas nos permite tener un servicio robusto, entendible y más importante aún escalable.

Cabe mencionar que los lineamientos descritos en este artículo son meramente subjetivos, que si bien están hechas con estándares de la IEEE, no son las únicas formas de realizarlas.

En una segunda parte de este manual de buenas prácticas hablaremos de los estados de respuesta, los métodos de petición, trabajo con versiones, etc.