DEV Community: Jose Ordoñez

Lo que necesitas saber para construir tu primer RESTful API

Jose Ordoñez — Thu, 10 Nov 2022 23:11:02 +0000

Usualmente este tipo de APIs sirven para exponer los datos de un sistema o aplicación, por lo tanto un CRUD puede ser expuesto por medio de REST en donde hay que olvidarse del estándar SOAP. Para crear una RESTful API primero necesitas conocer las bases de una Arquitectura Orientada a Recursos y entender cómo debes exponer, actualizar y crear los recursos de tu aplicación. Para iniciar con REST deberás considerar los siguientes puntos.

Manipulación de los recursos en REST

A diferencia de SOAP en donde hay diferentes alternativas de protocolos a utilizar, en REST no invertimos esfuerzos en tomar esta decisión ya que HTTP(S) es el protocolo utilizado. Para obtener un simple dato no necesitamos enviar un XML al servidor (como SOAP). Es suficiente realizar una petición GET a una URL por medio de HTTP, en donde la mayoría de veces no enviamos datos en este tipo de acciones, salvo algunos casos en donde es requerido por cuestiones de seguridad por mencionar alguno. En REST se puede utilizar XML o JSON para intercambiar datos aunque JSON es el más utilizado.

Por ejemplo para obtener la lista de productos basta con realizar un HTTP GET al recurso productos:

GET /api/productos -> https://host/api/productos

REST utiliza métodos HTTP

En REST se utilizan los métodos GET, PUT, POST, DELETE entre otros para indicar el tipo de operación que se desea realizar sobre el recurso.

GET: Se utiliza para obtener una representación de un recurso.

GET /api/productos - obtiene una lista de productos 
GET /api/productos/{idProducto} - obtiene los datos de un producto específico

POST: Se utiliza para crear una entidad a un recurso específico. En esta acción se debe adjuntar el JSON con los datos dentro del “Body” de la petición HTTP.

POST /api/productos - crea un producto nuevo
{
 "idProducto": "23",
 "nombre": "iPhone 11 Pro 256 GB",
 "descripcion": "Teléfono inteligente de Apple ",
 "precio": 1000.00,
 "rating": 4
}

PUT: Se utiliza para actualizar una entidad de un recurso específico. En esta acción se debe adjuntar el JSON con los datos dentro del “Body” de la petición HTTP.

PUT /api/productos/23 - actualiza los datos de un producto específico
{
 "nombre": "iPhone 11 Pro 256 GB",
 "descripcion": "Teléfono inteligente de Apple ",
 "precio": 850.00,
 "rating": 4
}

DELETE: Se utiliza para eliminar una entidad de un recurso específico. En esta acción se debe adjuntar en la url valor que identifica a la entidad dentro del recurso.

DELETE /api/productos/23 - elimina el producto específico basado en el id adjunto en la URL

Si te fijas bien, en REST las URLs no contienen verbos o acciones ya que el verbo HTTP nos indica la acción del recurso y el recurso está especificado dentro de la URL.

Tomando en cuenta lo anterior algo que NO deberías hacer es exponer tus recursos como:

POST /api/ObtenerProductos
POST /api/ActualizarProductos
POST /api/CrearProductos

Se recomienda que dentro de la URL no especifiques acciones o verbos como “CrearProductos”, “ObtenerUsuario” ya que por ser una arquitectura orientada a recursos estos recursos deben de ser accesibles y manipulables por medio de la URL y el verbo HTTP.

Los códigos de estado de respuestas HTTP

Un servicio REST debe de responder con códigos HTTP dependiendo de lo que quiera comunicarle al cliente. Esto permite que el cliente que consume el REST API pueda manejar diferentes escenarios de una mejor manera y que esto no impacte negativamente en la experiencia del usuario. Los más utilizados son:

200-299: Indican buenas noticias, ya que la petición fue aceptada.
- 200 OK: Indica que la operación fue realizada correctamente.
- 201 Created: Indica que la operación se realizó correctamente, se utiliza para indicar que se creó un recurso en un POST.
300-399: Indican redireccionamiento de una página a otra.
- 301 Moved Permanently: Indica redireccionamiento permanente.
- 302 Found: Indica redireccionamiento temporal, se diferencia del 301 en que toda las caracteristicas del SEO no se transportan a la nueva URL.
400-499: Indican que el cliente que hizo la petición no está en la capacidad de resolverla.
- 400 Bad Request: Indica que los datos dentro de la petición no eran los correctos, se utiliza en POST y PUT cuando no se cumple una validación o formato.
- 404 Not Found: Indica que el recurso solicitado no fue encontrado.
- 401 Unauthorized: Indica que el cliente no está autorizado a acceder al recurso por lo que es necesario identificarse antes de realizar la operación.
- 403 Forbidden: Indica que el cliente no tiene permisos, en este caso el cliente ya se identificó pero no tiene el permiso para acceder al recurso.
500-599: Indican el registro de errores en el servidor al que se hizo la petición.
- 500 Internal Server Error: Indica que algo falló y no está relacionado con ninguno de los errores mencionados anteriormente, por lo general esta respuesta es cuando algo falla de manera imprevista.
- 501 Not Implemented: Indica que la peticion hecha por medio del verbo no ha sido implementada o simplemente el servidor no tiene la capacidad para resolverla.
- 502 Bad Gateway: Indica que el servidor esta actuando como puerta de enlace o proxy y recibió una respuesta no válida del servidor original.
- 503 Service Unavailable: Indica que el servidor que está actuando como puerta de enlace o proxy recibió una respuesta no válida del servidor original, comunmente porque no esta disponible o esta caído.

Lenguajes y frameworks para construir una REST API

Para desarrollar tu primer REST API necesitas un lenguaje utilizado en backend, además puedes considerar un framework para facilitarte el proceso. Entre los más populares están:

Lenguaje	Frameworks
C#	ASP.NET Core/5/6/7
Java	Spring Boot, Quarkus, TomEE
JavaScript	Express, NestJS
Python	Flask, Django

Claro que existen más lenguajes y frameworks que podrías considerar, la elección de qué tecnología utilizar dependerá de factores como: experiencia previa en el lenguaje, lenguajes conocidos por tu equipo de trabajo, documentación disponible, ecosistema y restricciones de tu entorno, herramientas para el desarrollo, etc.

Al final la decisión será tuya o de tu equipo, elije la tecnología que cumpla con diferentes criterios previamente definidos. También puedes considerar solo el hecho de que quieres aprender algo nuevo, entonces debes buscar recursos para aprender como: documentación, libros, tutoriales y cursos en línea.

Con esta información en cuenta ya estás listo para empezar a construir tu primer REST API.

¿Por qué deberías considerar las RESTful APIs para la arquitectura de tu aplicación?

Jose Ordoñez — Thu, 10 Nov 2022 23:02:22 +0000

Acrónimos que encontrarás en la lectura:

Acrónimo	Significado
SOA	Service Oriented Architecture
SOAP	Simple Object Access Protocol
ROA	Resource Oriented Architecture
REST	Representational State Transfer

A lo largo del tiempo se han desarrollado estándares para el diseño y desarrollo de servicios web que permitan integrar diferentes sistemas y garantizar la interoperabilidad.

Los servicios web pueden clasificarse por su tipo de arquitectura entre los que destacan SOA y ROA. El framework basado en SOA es SOAP el cual sienta su base en servicios web, mientras que el framework basado en ROA es REST que también sienta su base en servicios web (Wagh y Thool, 2012).

Algunos expertos dicen que SOAP no está hecho para dispositivos móviles de recursos limitados. Los mensajes de SOAP tienen una carga pesada, por el contrario los mensajes del framework REST son de carga ligera por lo que lo hace el más adecuado para utilizarlo en dispositivos y redes móviles.

En la última década, se ha popularizado un estilo de arquitectura Software REST. Los Servicios Web que funcionan bajo REST (servicios Web RESTful) se presentan como una alternativa prometedora distinta a los servicios basados en SOAP por su simplicidad y naturaleza liviana, además de la capacidad de transmitir datos directamente sobre HTTP.

Para brindar escalabilidad e interoperabilidad a una plataforma es clave implementar una herramienta tecnológica que tenga la capacidad de ser reutilizada dentro de otra plataforma tecnológica que se requiera. Una arquitectura de software orientada a la recuperación de recursos como REST permite que una aplicación pueda ser invocada como servicio brindando la capacidad de poder acceder a sus funciones desde otra plataforma.

Sin importar el lenguaje de programación o framework en que sea desarrollado, un REST API permite comunicar diferentes sistemas y plataformas gracias al uso de HTTP. En la actualidad estas arquitecturas se pueden implementar tanto en infraestructura “On-Premise” como en una nube pública como Azure, AWS o GCP e incluso en un modelo híbrido que combine los 2 enfoques.

REST se coloca como una alternativa idónea si se desea implementar una aplicación multiplataforma, ya que tiene potencial para crear aplicaciones escalables así como la característica del escaso uso de recursos, características esenciales para el desempeño de una aplicación web y/o móvil.

Referencias

Wagh, K., & Thool, R. (2012). A comparative study of soap vs rest web services provisioning techniques for mobile host. Journal of Information Engineering and Applications, 2(5), 12-16

Why should you consider REST APIs for your application architecture?

Jose Ordoñez — Fri, 10 Jul 2020 07:21:52 +0000

Over time, standards for the design and development of web services came out in order to allow the integration of different systems and guarantee interoperability.

Web services can be classified by their type of architecture, among which SOA (Software Oriented Architecture) and ROA (Resource Oriented Architecture) stand out. The SOA-based framework is SOAP which lays its foundation on web services, while the ROA-based framework is REST which also lays its foundation on resources web services (Wagh and Thool, 2012).

Some experts say SOAP is not made for mobile devices with limited resources. SOAP messages have a heavy load, on the contrary, the messages of the REST framework are light load, which makes it the most suitable for use on mobile devices and networks.

In the last decade, a Software REST architecture style has become popular. RESTful Web Services are presented as a great alternative to SOAP-based services due to their simplicity and light nature, as well as the ability to transmit data directly over HTTP.

To provide scalability and interoperability to a platform, it is very important to implement a technological tool that can be reused within any other technological platform required. A software architecture oriented to the resources' recovery such as REST allows an application to be invoked as a service providing the ability to access its functions from another platform.

Regardless of the programming language or framework in which it is developed, a REST API allows us to communicate different systems and platforms thanks to the use of HTTP. Currently, these architectures can be implemented both in “On-Premise” infrastructure and in a public cloud such as Azure, AWS, or GCP and even in a hybrid model that combines the 2 approaches.

REST is positioned as an ideal alternative if you want to implement a cross-platform application since it has the potential to create scalable applications as well as the characteristic of low use of resources, essential characteristics for the performance of a web and/or mobile application.

References

Wagh, K., & Thool, R. (2012). A comparative study of soap vs rest web services provisioning techniques for mobile host. Journal of Information Engineering and Applications, 2(5), 12-16

6 Things you can do to become a better software developer

Jose Ordoñez — Sun, 16 Feb 2020 20:04:20 +0000

Months ago I was wondering about the journey that I had along with my career as a software developer and I could say that I’m “lucky” or “blessed” but I don’t trust in luck, I think you can build your destiny based on all the decisions that you make. So in these past years since I began my journey as a developer, I took some decisions and I always been trying to do some things that helped me a lot to improve my skills in this field. I would like to share with you 6 things that I applied and helped me to improve myself.

1. Read Books/magazines/blogs

I'm not a great reader, I have difficulties focusing while I'm reading but I think read is very important. Since I don't have a reading habit I just read some books so far, I'm not the one that reads tons of books but I have to admit that read books help you to grow and learn new things. I'm a person that maybe doesn't reads a lot of books but reads a lot of articles in magazines and blogs, I invest at least 30 minutes every day (I try) reading blogs or articles. This practice helped me to discover new alternatives to do my job, new techs, new frameworks that at some point I've been using and helped me to improve my job. You can start investing some minutes to read about a topic that you want to specialize in or a topic that you want to learn. In my case each day I try to read one article about a tech or a stack that I'm familiar with (backend or DevOps) and also I read one article about some tech or stack that I want to learn (frontend and product management).

2. Read other's code (especially Open Source projects)

During my career and different jobs, I've been working on projects that are already built so I've faced code written by other developers, which was great no matter if that code was bad or well built. Reading other's code allows you to gain new knowledge. Maybe you can learn new design patterns, code standards and sometimes you learn how not to code. I also recommend reading the code from Open Source projects, if you use some libraries or tools that you like maybe you can spend some time reading the code and its documentation.

3. Develop a personal project

You may have all the theory inside your head but the only way you can prove your value is by demonstrating what you've learned. As a Developer build things will help you to improve your skills, in software development the "practice makes perfect". You can develop an App or Tool to learn a new language, framework, or design pattern, from my perspective there is no better way to learn than put it into practice.

4. Know SW architecture and Design Patterns (before knowing a lot of programming languages).

I think is great to learn different programming languages. When you see that developer that knows 5 different programming languages you just think it is awesome that someone takes its time to learn different programming languages. You think that Dev is a superhero, the disappointment comes when you read that developer’s code or you watch him submitting bugs to production. So I think that if you don’t know good coding standards, coding principles, software architecture approaches, and design patterns you will make the same mistakes in every programming language. I could say that those aspects are agnostic to programming languages and a good developer should focus on polish those aspects before getting obsessed to learn a lot of programming languages.

5. Listen to experienced professionals

In every job that I had, I always tried to listen to the experienced co-workers and that is something that I didn’t regret it, we can learn a lot about the experiences (bad or good) from others. You know, listen to the difficulties of others can help you to avoid the same difficulties to you, and listen to the achievements and success of others can inspire you to do great things. So always try to accept advice or a critic, listen to what the others have to say because sometimes they are spending some of their time to help you to be better.

6. Teach or mentor others

Now on the other side, I also try to be someone that helps the less experienced to improve. This is not rocket science, this is about to guide or help others when they need it. In a situation when you’re teaching or mentoring I think that your technical skills could increase. In my particular case, I experienced the “learning by teaching” and it’s doubly satisfying.

Well, those are the “tips” that I can share with you so far, maybe some of them are obvious but the key is to just do it. If you have more tips or comments you can share with us.

Thanks for reading.

Deploying Infrastructure to Azure with Terraform and Azure DevOps

Jose Ordoñez — Sun, 16 Feb 2020 01:23:46 +0000

At this tutorial we’ll build an automated pipeline that allows to create infrastructure in Azure cloud using IaC concept with tools such as Terraform and Azure DevOps.

We will be able to create a PaaS Azure Resource called App Service. This Azure resource allows to deploy a web app, for this sample a .net web app.

For this tutorial you can use the files from this repo, you can fork it to your account if you want. Within those files is a folder called Terraform and a file called appService.tf that contains infrastructure’s definition that will be deployed on Azure. The file contains the definition for the following Azure resources:

Resource Group
App Service Plan
App Service

Each resource has its required configurations such as the name and other parameters. If you use the terraform file from this repo you should change the name for your App Service resource since this should be a unique name within azure cloud.

Requirements

Install Azure CLI (if you want to test from your computer)
Install Terraform (if you want to test from your computer)
Create an Azure account.
Create an Azure DevOps account.

To be honest with you for this tutorial you don’t even need Azure cli or Terraform installed on your machine since Azure DevOps will do the magic.

Create Azure DevOps Project

If you already have an account you can skip this section. In order to create an Azure Pipeline you must create your Azure DevOps project that will contain the automated pipelines that deploy the infraestructure to the cloud.

Create New Organization

Open https://dev.azure.com
Create a new organization

Create Project

Create the first project - name it, in my case AzBootCamp2019

Authorize your Azure Cloud subscription

Add a service connection for your Azure Subscription

Create Automated Pipeline

After you create your organization and project within Azure Devops you can proceed now to create your automated pipeline.

Create a Release Pipeline

This pipeline will allow us to set different required steps that execute our different tasks to deploy the infrastrucuture to the cloud.

Create a new Release Pipeline
Add an artifact, in this case your Github repo where your terraform code is hosted. You should add a new connection to your github in services management.
Add a stage, e.g.: Dev or Prod. This stage should be an empty job.

Select an Ubuntu OS Agent

For this sample you should use an agent that runs with Ubuntu OS since the scripts are written in bash.

Create Pipeline variables

These pipeline variables will be used in order to parametrize names for some resources and avoid the hardcoding within the scripts. These variables will be used to create the Azure resources that will store the Terraform Backend. The variable "TerraformStorageAccount" refers to the name that you will set to the storage account in Azure that will stores the Terraform Backend, this variable should be different for any implementation since this should be a unique name within Azure Cloud.

Terraform Backend

By default, Terraform stores state locally in a file named terraform.tfstate. When working with Terraform in a team, use of a local file Isn’t a great idea. You can use the remote state that allows Terraform to writes the state data in a remote data store that you can specify. For this sample we will use a Terraform CLI task that allows to create an Azure storage account and storage container to store Terraform state if this not exists yet. For more information on Terraform remote state click here

Terraform Cycle

When running Terraform in automation, the focus is usually on the core plan/apply cycle. The main Terraform workflow is the following:

i. Initialize the Terraform working directory.

ii. Produce a plan for changing resources to match the current configuration.

iii. Apply the changes described by the plan.

The following tasks will allow you to implement the terraform cycle.

Add Task - Terraform Init

First you should install the extension in order to use the terraform task, for this tutorial we use an specific extension, select the extension created by Charles Zipp.

Once the extension is installed in your Azure DevOps you can add the task for Terraform Install, this task will guarantee that the agent that runs the command has Terraform installed.

Add Terraform CLI task to perform the Init Stage, you should select the command “Init” and for the Configuration directory you should point to the artifact configured before (repo and folder that contains the terraform files).

Configure the Azure Resource Manager section in order to set the Terraform Backend that will be located in azure, we should use the Pipeline variables configured previously.

This task runs terraform init command. The terraform init command looks through all of the *.tf files in the current working directory and automatically downloads any of the providers required for them. In this example, it will download Azure provider as we are going to deploy Azure resources. For more information about terraform init command click here.

Add Task - Terraform Plan

Add Terraform CLI task like the init task, but for this one you should select the command “Plan”. You should set the Configuration Directory like the previous task. Also set the "Environment Azure Subscription" that should point to your Azure service connection configured before, you should authorize the connection if necessary.

The terraform plan command is used to create an execution plan. Terraform determines what actions are necessary to achieve the desired state specified in the configuration files. This is a dry run and shows which actions will be made. For more information about terraform plan command click here.

Add Task - Terraform Apply

Add Terraform CLI task like previous tasks, but for this one you should select the command “Apply”. You should set the Configuration Directory like the previous task. Also set the "Environment Azure Subscription" that should point to your Azure service connection configured before.

This task will run the terraform apply command to deploy the resources to Azure Cloud.

Save your Pipeline

Once the pipeline configuration is completed set a Name on it and save changes.

Launch your Pipeline

Here we go, the Pipeline is now available! So now we can Create a Release, this action will start the execution of the pipeline and its tasks.

When the pipeline’s execution is completed you will be able the see the new infraestructure created in Azure.

Within the RG for the App Service you will see the new infrastructure.

So we have an Azure App Service created that can be able to host a web app (.net for this tutorial). If you want to deploy an App Service with more compute capacity or different Runtime (maybe Docker) you can easily do that changing your infrastructure definitions on the .tf file.

Thanks for reading!