DEV Community: Vinícius A. dos Santos

Software Engineering vs Video Games

Vinícius A. dos Santos — Mon, 01 Mar 2021 15:46:25 +0000

Well, since I was a kid, I loved to play video games. Started with Mega Drive, playing Sonic. Then my brother earned a PlayStation, I loved to play "Crash Bandicoot". The consoles generation were evolving and I followed until Xbox 360.

I don't play video games anymore.
I was thinking about that and realized that I don't miss it, but I didn't loose that feeling and I know why that happens.

What I liked on video games was to complete missions, achieve the best results possible.
Do you know those kind of games that you can finish doing about 70 percent of you could do on the game stages? To achieve 100 percent of completion, you needed to do some side tasks, take all the gold coins scattered through the stage, and things like that.
I was the kind of player that wished to reach 100 percent of completion. It wasn't always possible (after all, sometimes it's so difficult and time consuming that it doesn't worth it), but I was always trying to make it.

I reach those feelings I felt playing video games while developing software.
Whenever a suite of unit tests passes, a request of a Rest API I implemented works, the Stakeholders' feed-backs are positive, it's like completing a video game stage, defeating a boss, winning the game.
It's so satisfying...
Also, I don't aim to achieve 70 percent completion, that is, delivering a feature that works in a functional way. I want 100 percent. I want the cleanest code, the most secure level, the best performance possible. But by the same way I used to think while playing, sometimes it doesn't worth the effort and time consumed to achieve this.
I have in mind things like time-to-market, agility and generating value for company in order to decide when it's worth waste more time trying to achieve 100 percent.

Does it makes sense for you?

When to change a Rest API version

Vinícius A. dos Santos — Fri, 12 Feb 2021 21:04:43 +0000

Hi, everyone!
If are familiar with de concepts of API, you know that most of time it's built to other developers to consume it. It doesn't matter the kind of API: HTTP API's, libs, packages, etc. Either it is a external API, for anyone in the world who ask you for an API key or an internal API for other teams inside same company.

Yesterday a colleague from the company I'm currently employed complained about a breaking change in a Rest API his application consumes from another team.

He wasn't advised about the change and his application broke in production.

Actually, a breaking changing in a Rest API shouldn't happens even when advising all the consumers.

The risk is to high, you may forget someone. Besides that, everyone should synchronize the change so the application users have no impact.

So I'm listing some rules to guide us about when to generate a new version of a Rest API instead of simply changing it in the current version.

Changes that requires generating a new API version

Removing a resource. E.g. api.com/store is been removed;
Removing a method of a resource. E.g. PUT on api.com/store/products/123 is been removed;
Removing an API path. E.g. api.com/store/products is been removed;
Removing a query param of a request. E.g. query parameter ?color=red is been removed;
Renaming a query parameter. E.g. query parameter ?color=red now is ?product-color=red;
Renaming a body attribute on request or on response. E.g. { ..., "color": "red" } now is { ..., "product-color": "red" };
Turning a parameter from optional to required, either path param, query param or the request body;
Changing acceptable values for an enumerator param;
Denying a content-type that was accepted earlier, either on response or request;
Adding a required request header;
Removing a response header;
Removing a response body attribute;
Changing a parameter or attribute type, either on the request or response;
Increasing restrictions for as parameter, either a path, query string or body param. E.g not not accept attribute name over 50 characters;
Changing default value of an optional parameter. E.g. default value for payment-method if it is not informed will be credit, but it used to be debit;
Adding a new Http Status Code response. E.g. when there aren't any products in the bag, GET products used to return Http 200 and an empty array, but now it gonna return 404;
Removing a Http Status Code response. E.g. opposite of the above example.

Changes that may be handled on the current API version

Adding a new resource;
Adding a new supported method to an API resource;
Adding a new resource path;
Turning to optional a required parameter, either it is a path, query string or body attribute param;
Adding new optional parameters;
Adding new attributes to an API response.

AWS API Gateway + Terraform + Serverless Framework - Part 1

Vinícius A. dos Santos — Fri, 12 Feb 2021 12:44:27 +0000

Hi, everyone!
For this "Hands on!" we're going to build an REST API with AWS API Gateway, provisioned with Terraform and backed by AWS Lambda built with Serverless Framework.

The REST API will allow us to send SMS Messages using AWS SNS. Sounds like a lot of things, but it's no that lot of working.

For this part 1, we'll provision our API Gateway with Terraform and for part 2 and 3:

Part 2: coding the backend with Serverless Framework

Part 3: securing the API with Amazon Cognito

About the tech stack

AWS: Most popular Cloud provider. You need an account to follow this article properly;
AWS API Gateway: AWS managed API Gateway that will expose our rest endpoints;
AWS Lambda: serverless functions on AWS working as our backend;
AWS SNS: AWS Simple Notification Service that, among other types of notifications, allow us to send SMS for a phone number;
Terraform: IaC (Infrastructure as Code) tool that allow us to provision cloud resources supporting several cloud providers;
Serverless Framework: a Framework for support building and deploying serverless functions grouped as a Serverless Service, allowing also the provisioning of resources need for these functions;
NodeJS: JS runtime where our JavaScript lambda functions gonna be running;
JavaScript: Of course, the programing language we'll write our lambda.

Why Terraform, since Serverless Framework itself can provision AWS resources?

Well, it's very common to have an API Gateway serving different backend services.

Ex: endpoint X points to a serverless function, endpoint Y points to Java Spring Boot Microservice, endpoint Z points to third-party API.

If the API Gateway gets provisioned by the serverless Service, it's infrastructure code gonna be highly coupled to this service and you need to implement the other types of integrations using this service as a proxy (creating more lambdas and increasing the infrastructure cost and complexity).

Also, if you destroy this Service, the API Gateway gonna be destroyed too.

So, hands on!

Terraform AWS API Gateway provisioning

If haven't Terraform installed, do it: https://www.terraform.io/downloads.html.

When provisioning resources, the docs helps a lot: https://www.terraform.io/docs/providers/aws/index.html.

Nobody should try to memorize the code for the whole bunch of services AWS provides.

First, we need set the cloud provider configurations.

Let's create file provider.tf like this:

# provider.tf
provider “aws” {
    region = “us-east-1”
    version = “2.61”
    access_key = "your-access-key”
    secret_key = "your-secret-key” 
}

We are telling terraform that our provider is AWS and we want provision resources on us-east-1 region.
We're also setting aws credentials having the roles and policies needed to manage API Gateway (we could set the credentials as environment variables as well).
I's important set the version of terraform aws plugin to avoid upgrades with breaking changes issues.
Now, we can init terraform in this project running in terminal:

$ terraform init

You should se the message Terraform has been successfully initialized!.

To finally provision an API Gateway, let's create another .tf file as follows:

# api-gateway.tf
resource "aws_api_gateway_rest_api" "my_api_gateway" {
  name        = "My API"
  description = "AWS Rest API example with Terraform"
  endpoint_configuration {
    types = ["REGIONAL"]
  }
}

resource: provision a cloud resource to be managed by Terraform;
aws_api_gateway_rest_api: the type of resource;
my_api_gateway: a name to reference this resource in this project.

The content inside the block refers to attributes of the API Gateway. You can look at AWS API Gateway if you are not familiar.

We can now execute the command below to check what Terraform gonna do after we apply the provisioning plan:

$ terraform plan

Among other output messages, you should see:

Terraform will perform the following actions:
  # aws_api_gateway_rest_api.my_api_gateway will be created
  + resource "aws_api_gateway_rest_api" "my_api_gateway" {
      + api_key_source           = "HEADER"
      + arn                      = (known after apply)
      + created_date             = (known after apply)
      + description              = "AWS Rest API example with Terraform"
      + execution_arn            = (known after apply)
      + id                       = (known after apply)
      + minimum_compression_size = -1
      + name                     = "My API"
      + root_resource_id         = (known after apply)
      + endpoint_configuration {
          + types = [
              + "REGIONAL",
            ]
        }
    }
Plan: 1 to add, 0 to change, 0 to destroy.

As we can see on the last line, Terraform gonna add 1 resource, change none and destroy none.

It's not guaranteed that this plan will be exactly the same applied. So we could use $ terraform plan -out, but this plan is pretty simple.

To really apply the changes, the command is:

$ terraform apply

Then exactly plan to be executed will be presented again and you can answer yes.

Going to AWS Console and looking for API Gateway Resource (region us-east-1), we can see the API created:

But clicking on it, there's no api resources paths:

Let's define that our API base path gonna be <api-url>/my-api/v1.
Back to Terraform files, we add this code:

# api-gateway.tf
resource "aws_api_gateway_rest_api" "my_api_gateway" {
  ...
}

resource "aws_api_gateway_resource" "my_api" {
  rest_api_id = aws_api_gateway_rest_api.my_api_gateway.id
  parent_id   = aws_api_gateway_rest_api.my_api_gateway.root_resource_id
  path_part   = "my-api"
}

resource "aws_api_gateway_resource" "v1" {
  rest_api_id = aws_api_gateway_rest_api.my_api_gateway.id
  parent_id   = aws_api_gateway_resource.my_api.id
  path_part   = "v1"
}

aws_api_gateway_resource: the type of resource is api gateway resource;
rest_api_id: the id of the API Gateway that owns this resource;
parent_id: the id of parent path, which is the root "/" of the API Gateway;
path_part: the path part we want to create.

Note that for "v1" resource, the parent_id is the id of "my_api" resource, thus the complete path gonna be "/my-api/v1".

Running apply again:

$ terraform apply

We should see on AWS Console three API resources ("/", "my-api" and "v1"):

That's it for this post. In part 2 we're going to implement backend with Serverless and part 3 we'll implement authentication with Amazon Cognito: