DEV Community: Claudio Altamura

Clean and maintainable Git Histories – Part 2

Claudio Altamura — Fri, 28 Nov 2025 18:05:26 +0000

3 simple tricks for managing git histories

It took me a while to learn these simple tricks for effectively managing Git histories with just a few commands. In the first article, I explained why clear, structured Git commit messages and cohesiv commits are important or why temporary commits make the history more difficult to read. This time, I will show you how to organise your commits before merging them. This will give you a clean, easy-to-understand commit history.

Changes should be reviewed and consolidated into a clear commit history. The aim is to include only changes that are relevant, just like book authors revise drafts before publishing. Consider cleaning up commit history for clarity and maintainability:

Add changes directly to the previous commit
If you make minor adjustments to the last commit, you can add them directly into the previous commit by utilizing git commit --amend
Consolidate multiple commits into one single commit
All changes can be grouped together into a single commit with
git merge --squash
Tidy up your commits
Remove temporary commits, combine multiple commits into one or change the content to create a simple, easy-to-read history with git rebase

Add changes directly to the previous commit

You can make minor corrections or unnecessary changes directly in the last commit using git commit --amend. This command lets us add new files, remove unwanted files or change the commit message – all without creating a new commit (simplified). Here's how to make changes:

Open your files in the working directory, and then either add new files using git add or remove files that you don't need any more using git rm
Now you can adjust a commit by adding the changes to the last one using the git commit --amend command.
You can also edit the commit message if you want.
And when the commit is already been pushed, you'll need to force push to the remote repository with git push --force-with-lease.

Consolidate multiple commits into one single commit

During development, you usually work in your feature branch and create several commits like partial steps, WIP commits or bug fixes. Often these intermediate states are not relevant for the main branch and inflate the history. In such a case, the changes can be reduced to one single, clean commit.

Before merging into the main branch, you can squash your commits so that only one summary commit appears in the main branch. The detailed intermediate steps in the feature branch are not retained – instead, a clear, complete commit is created that describes the entire change. Here is an example:

git checkout main
git merge --squash <feature-branch>
git commit -m "feat(auth): add JWT authentication"
git push origin main

This method makes sure you've got a tidy and clear commit history by presenting the whole change as one completed commit – perfect for feature developments with lots of intermediate stages. This makes code reviews a lot of easier. And the main branch is kept simple and free of any unnecessary steps.

Disadvantages like losing granularity because you lose contextual information, or more complex conflict resolution because squash bundles multiple changes into one large commit, are often not that important.

Tidy up your commits

You can use git rebase -i <commit-hash> to edit the commit history interactively and to tidy up the commits. This is really useful for getting rid of temporary or debug commits, or for merging multiple commits. Let's say we want to edit the last five commits with git rebase -i HEAD~5. This will show you a list of the last five commits:

pick abcdef1 Commit A
pick abcdef2 Commit B
pick abcdef3 Commit C
pick abcdef4 Commit D
pich abcdef5 Commit E

Now you can edit the commits as you like:

Change pick to squash for the commits you want to merge.
Use fixup, if you want to stick changes or corrections made in later commits into an earlier one, but you don't want to keep the message from the later one.
You can use the drop command to get rid of individual commits from the history. This is great for temporary or debug commits.
And use edit to make changes to a commit. Git stops at this point in the rebase process, so you can make changes in the working directory, like remove debug output or undo temporary changes.

Then just save those changes and you're all set! Now that you've changed the commit history, I think it's important to mention that you'll need to perform a forced push to update the changes in the remote repository using git push --force-with-lease.

A rebase cleans up the Git history. It makes the history linear, as if all the changes from your feature branch were applied directly to the latest version of the main branch. And there's no merge commit created that is causing any issues.

Just be careful:

If you re-write history, you might lose sight of the original context, especially when and how changes upstream were integrated.
If you rebase branches that have already been published, you might run into problems because you'll be changing the history. Other team members working on the same branch will run into conflicts and have to readjust their local changes.

Conclusion

In this two-part series of articles, we've taken a close look at keeping Git histories easy to understand and to maintain. This is something that often gets overlooked, but it's actually really important making sure the team works efficiently.

Links

Rewriting history https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History

Photo by Tobias Reich on Unsplash

Clean and maintainable Git Histories – Part 1

Claudio Altamura — Wed, 09 Jul 2025 19:15:16 +0000

3 methods for keeping histories clean and organized

In this series of articles, I'm going to show you how to get clean and maintainable git histories. In the first part, we look at different methods. If these methods are followed, the history remains clear, facilitates code reviews, debugging and can serve as documentation:

Meaningful commit messages
A clear description of the change and its motivation
Cohesive commits
Only changes that belong together should be included in a single commit
Avoid temporary commits
WIP, temporary or debug commits should not be merged to keep the history clean

Meaningful commit messages

Everythings starts with a clear commit message. It should briefly summarize what was changed and why. Conventional Commits offer us a reliable format for commit messages, enhancing the clarity and comprehensibility of source code histories. A commit message should include:

Type: The type of change (e.g., fix, feat).
Scope (optional): The affected area of the project.
Description: A brief description of the change.
Body (optional): Additional details about the change.
Footer (optional): Metadata, e.g., references to issues.

Here is an example of such a commit message:

feat(auth): add JWT authentication
This commit introduces JSON Web Token (JWT) based authentication to the login module.
BREAKING CHANGE: The login API now requires a token for authentication.

Cohesive commits

A commit should be atomic, containing logically related changes that should not be split up. Each commit should represent a standalone change, whether it's a bug fix, a feature enhancement, or a code refactoring. This practice simplifies change tracking and finding errors more quickly. It provides a clear overview of the modifications made and the reasons behind them, also streamlining the code review process. By isolating each change, reviewers can concentrate on specific modifications without feeling overwhelmed by a large number of changes. Moreover, in case of issues, reverting changes becomes significantly more straightforward, minimizing disruptions to the overall project.

Let’s take the previous example and explain the commits in more detail:

Commit 1: feat(auth): setup JWT library and utility class
Commit 2: feat(auth): configure security with JWT filter
Commit 3: feat(auth): modify login API to return JWT token
Commit 4: test(auth): add unit tests for JWT authentication
Commit 5: docs(auth): update README with authentication instructions

Commit 1 adds the JWT library and creating the utility class
Commit 2 includes a JWT Filter into the security configuration
Commit 3 focuses on the specific change to the API
Commit 4 is dedicated to tests to ensure that the new functionality is fully covered
Commit 5 contains only documentation changes

Aim to create real cohesive commits, not just small, chronological commits. The purpose of commits is to explain what changed and why, not to document every step. This leads to a cleaner Git history, helps to improve code quality and maintainability.

Avoid temporary commits

While in the process of development and debugging, it's important to be mindful of the impact of WIP (Work in Progress) and debug commits on the clarity of a code repository. These types of commits can introduce steps that do not reflect the final implementation, leading to complications in tracking progress on features or bug fixes.

Take, for example, a common debug commit where a developer adds println statements to monitor variable behavior during code execution. It is essential to clean up these debugging statements once the debugging phase is complete.

Below are some commit samples that are not suitable for merging:

Commit 1: feat(user): first version UserService
Commit 2: refactor(user): UserService - Tests not working
Commit 3: debug(auth): added printlns to check flow

To maintain a clear and detailed project history, it is advisable to rewrite the commit history for consolidating work-in-progress commits, eliminating temporary and debug commits prior to merging, ensuring that only important and production-ready updates are integrated into the main branch.

Conclusion

These 3 methods help to structure and maintain project histories. This includes clearly defined commit units, meaningful commit messages and that only production-relevant changes are merged into your primary branch. Just like book authors revise drafts before publishing, consider cleaning up commit history before sharing it.

So stay tuned for the second part, where we delve into techniques for cleaning up and consolidating commits.

Links

Conventional Commit https://www.conventionalcommits.org/en/v1.0.0/#summary

Photo by Markus Spiske on Unsplash

Reinstalling Your Must-Have Dev Tools and Extensions on Mac

Claudio Altamura — Fri, 09 Aug 2024 12:30:23 +0000

A step-by-step guide to bringing your essential development setup back to life.

So, you’ve got a shiny new Mac, and you’re ready for a fresh start. But where do you begin? Installing the right tools and applications is crucial to get your development environment up and running smoothly. In this guide, I’ll walk you through using Mac terminal commands to streamline the installation process for essential programs like Homebrew, Visual Studio Code or SDKMAN. Let’s get your Mac setup right 💻!

Which applications have I installed?
If you want to see a list of all the applications installed on your old Mac before you start fresh on a new one, the terminal has a handy command for that. Simply open the Terminal and run the following command:

ls -1 /Applications

...
Discord.app
Docker.app
GIMP.app
...

It's worth noting that the list generated by this command includes all applications in your /Applications folder, even those that can be easily reinstalled with Homebrew

Homebrew
You're a using Homebrew? Okay, then you’ll should do is to get a list of the software you have installed on your old Mac. Launch the Terminal, then execute this command:

brew list -1

==> Formulae
azure-cli
azure-functions-core-tools@4
base64
borgbackup
...

Visual Studio Code Extensions
To list all the Visual Studio Code extensions you’ve installed, you can easily do so by opening a terminal and typing the following command:

code --list-extensions

This will give you a straightforward list of all your extensions. But if you want to take it a step further—you can use the following command to generate a series of commands that will reinstall each extension:

code --list-extensions | xargs -L 1 echo code --install-extension

This command creates a list where each line is a command to install one of your extensions, like this:

...
code--install-extension editorconfig.editorconfig
code--install-extension esbenp.prettier-vscode
...

With this list, you can easily reinstall all your VS Code extensions on your new machine with minimal effort, ensuring your development environment is back to how you like it in no time.

SDKMAN!
If you're using SDKMAN to manage your JDKs and other SDKs, there's one more handy command worth mentioning. By running:

tree -L 2 ~/.sdkman/candidates/

you can quickly visualize all the SDKs and JDKs you have installed. This command provides a neat directory tree that displays each SDK along with its version, like so:

...
├── gradle
│   ├── 8.3
│   ├── 8.4
│   ├── 8.5
│   ├── 8.6
│   └── current -> 8.6
├── java
│   ├── 11.0.16.1-tem
│   ├── 17.0.4.1-tem
│   ├── 17.0.8.1-tem
│   ├── 21.0.1-tem
│   ├── 21.0.2-tem
...

This structured view not only shows the versions you have installed but also highlights the one currently in use, marked by the current symlink. It’s a great way to quickly assess your development environment and ensure you have the right versions set up before diving back into coding on your new Mac.

Conclusion ✨
And with that, we've come to the end of our guide on setting up your new Mac with all the essential development tools. Getting your new Mac set up with the right tools is the first step to a smooth and productive development environment. With some terminal commands you’re well on your way.

If you found this guide helpful, make sure to follow me for more tips and tricks on software development 😊.

Photo by Maxim Hopman on Unsplash

Validate your specs with OpenAPI Style Validator

Claudio Altamura — Fri, 28 Apr 2023 14:24:12 +0000

OpenAPI Style Validator is a tool to create API specs with understandable descriptions, examples and consistent use of naming conventions.

The Validator helps developers to identify issues in OpenAPI specifications. With defined rules you can describe exactly how an API specification should look. These specs can be checked automatically and the results can be used in code reviews or even in a build pipeline where rule violations result in a build break.

Complete descriptions and naming conventions
The validator checks various objects of the OpenAPI schema, starting with the info object and the associated contact and license object. Often these details are not provided at all. Here you see as an example how the popular Petstore example provides the details.

{
"info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "description": "A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "name": "Swagger API Team",
      "email": "apiteam@swagger.io",
      "url": "http://swagger.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  }
}

The next object we'll take a closer look at is the operation object. But let's start with the paths object. The paths object contains all the paths to existing endpoints (path items). A single path (/pets) contains operations which describe what http methods are allowed.

{
"/pets/{id}": {
    "get": {
      "description": "Returns a user based on a single ID, if the user does not have access to the pet",
      "operationId": "find pet by id",
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "ID of pet to fetch",
          "required": true,
          "schema": {
            "type": "integer",
            "format": "int64"
          }
        }
      ],
    }
   }
}

The OpenAPI Style Validator detects whether certain properties exist For example, the property "summary" is missing in the above listing. In contrast, a "description" is present. The absence of a property is an error, if you have configured it that way.

Let's look how the OpenAPI Style Validator checks the data type descriptions. Data types are defined in the OpenAPI specification as schema objects that can be referenced in requests or responses (e.g. "$ref": "#/components/schemas/NewPet"). The validator can check if all schema properties like description and example are present and not empty.

{
"NewPet": {
    "type": "object",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string"
      },
      "tag": {
        "type": "string"
      }
    }
  },
}

If we look at the NewPet schema object in the above listing, we do not find descriptions and examples. Examples and descriptions in an API spec make the documentation more understandable.

Now let's move on to naming conventions. Naming conventions help to make an API easier to use. The OpenAPI Style Validator supports a number of different conventions that we can apply to paths, path parameters, query parameters, cookies, headers and properties. The naming conventions are: the underscore case (snake_case), camel case as we know it from Java and JavaScript and the so called hyphen case, also known as Kebab Case.

Options and launching the OpenAPI Style Validator
With the defined rules we have learned now, we can control how an OpenAPI specification has to look. What kind of options do we have? There are boolean options like "validateOperationOperationId", which by a true, requires that each operation has an id. The option "validateOperationSummary" requires that operations also have a description. But there are also string type options like pathNamingConvention, parameterNamingConvention, pathParamNamingConvention and queryParamNamingConvention. With these options, we can determine if elements should follow e.g. the underscore case or camel case naming convention.

So, how do we launch the validator? The maven command looks like this:

mvn openapi-style-validator:validate

For Maven the OpenAPI Style Validator plugin must be configured inside the pom.xml Currently, io.swagger.core.v3 dependency must be excluded, otherwise a newer version of the library is used which unfortunately is incompatible with version 1.8 of the OpenAPI Style Validator. As you can in the following listing, each option can be added as a parameter under an XML tag, e.g. "validateOperationSummary" with true or false as text content.

<plugin>
<groupId>org.openapitools.openapistylevalidator</groupId>
<artifactId>openapi-style-validator-maven-plugin</artifactId>
<version>1.8</version>
<configuration>
    <inputFile>petstore-expanded.json</inputFile>
</configuration>
<dependencies>
    <dependency>
        <groupId>org.openapitools.empoa</groupId>
        <artifactId>empoa-swagger-core</artifactId>
        <version>2.0.0</version>
        <exclusions>
            <exclusion>
             <groupId>io.swagger.core.v3</groupId>
                <artifactId>swagger-models</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
</dependencies>
</plugin>

And by the way, with the default configuration we get the following result for the Petstore example:

[INFO] --- openapi-style-validator:1.8:validate (default-cli) @ openapitools-validator-mvn-example ---
[INFO] Validating spec: petstore-expanded.json
[ERROR] OpenAPI Specification does not meet the requirements. Issues:

[ERROR]         *ERROR* in Operation GET /pets "summary" -> This field should be present and not empty
[ERROR]         *ERROR* in Operation GET /pets "tags" -> The collection should be present and there should be at least one item in it
[ERROR]         *ERROR* in Operation POST /pets "summary" -> This field should be present and not empty
[ERROR]         *ERROR* in Operation POST /pets "tags" -> The collection should be present and there should be at least one item in it
[ERROR]         *ERROR* in Operation GET /pets/{id} "summary" -> This field should be present and not empty
[ERROR]         *ERROR* in Operation GET /pets/{id} "tags" -> The collection should be present and there should be at least one item in it
[ERROR]         *ERROR* in Operation DELETE /pets/{id} "summary" -> This field should be present and not empty
[ERROR]         *ERROR* in Operation DELETE /pets/{id} "tags" -> The collection should be present and there should be at least one item in it
[ERROR]         *ERROR* in Model "NewPet", property "name", field "example" -> This field should be present and not empty
[ERROR]         *ERROR* in Model "NewPet", property "name", field "description" -> This field should be present and not empty
[ERROR]         *ERROR* in Model "NewPet", property "tag", field "example" -> This field should be present and not empty
[ERROR]         *ERROR* in Model "NewPet", property "tag", field 'description' -> This field should be present and not empty
[ERROR]         *ERROR* in Model "Error", property "code", field 'example' -> This field should be present and not empty
[ERROR]         *ERROR* in Model "Error", property "code", field 'description' -> This field should be present and not empty
[ERROR]         *ERROR* in Model "Error", property "message", field "example" -> This field should be present and not empty
[ERROR]         *ERROR* in Model "Error", property "message", field "description" -> This field should be present and not empty
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.342 s

Links
OpenAPI Style Validator
Petstore Beispiel
Validation example

Photo by Yassine Khalfalli on Unsplash

Project Pilot - Short Notes

Claudio Altamura — Wed, 28 Dec 2022 13:51:26 +0000

Series on Software Design Practices – Part 3

In this small series on design practices, I write about various practices. In every article, I give a brief and simple explanation. In part 2 I wrote about prototypes. This time I present project pilots as another software development design practice.

We already talked about spikes, which help you to find approaches for a technical problem, or prototypes to test a specific concept. What these concepts have in common is that they should not be used in production. Spikes may not be good enough or prototypes only focus on feasibility.

Right here comes in the so-called project pilot. You add additional points regarding production readiness, that you are able to test the viability and how likely it is that the software succeed. So it's the first phase in a larger project with a defined productive scope. And very importantly, project pilots provide you valuable feedback on ideas and concepts.

Project pilots are another good strategy for managing risk. The concept helps you to uncover potential flaws ahead of a full launch. Use this feedback to identify issues and correct them in advance.

Photo by Benjamin Elliott on Unsplash

Prototype - Short Notes

Claudio Altamura — Wed, 30 Nov 2022 20:50:34 +0000

Series on Software Design Practices - Part 2

In this small series on software design practices, I write about various practices. In every article, I give a brief and simple explanation. In part 1 I wrote about Spike Solutions. This time I present prototypes as a software development design practice.

A prototype is a simplified, functional model of a planned product or component. It serves as a preparation for production, but can also be used to illustrate a specific concept. The prototype is often the first milestone in a project to test the suitability and acceptance of a new technology, application or process.

The prototype is an essential development step regarding the future solution. However, it should not be used in production after the feasibility check. The building blocks, on the other hand, can be used and improved in the final solution.

Photo by Hal Gatewood on Unsplash

Spike Solutions - Short Notes

Claudio Altamura — Mon, 31 Oct 2022 16:40:31 +0000

Series on Software Design Practices - Part 1

In this small series on software design practices, I write about various practices. In every article, I give a brief and simple explanation. This is part 1. Let's start with spike solutions.

For me a spike is a way to figure out answers to a technical or design problem. It's a solution to explore potential solutions. You make a spike to reduce the risk of a technical problem or to achieve a better estimate for a user story.

Spike solutions could be technical or functional. Functional spikes help you to analyze an overall solution.

What is to be done?
How do we break the work into smaller pieces?
Where is the complexity hidden?

Technical spikes on the other side are a way to find different approaches for a problem, e.g.

specific technical implementation
or to get confidence that the chosen strategy works out.

Experience has shown that first you should focus on the problem with the spike and ignore other concerns, second not all spike solution are good enough to deploy in production. And at last, demos and discussions about the approaches are highly valuable steps.

Photo by charlesdeluvio on Unsplash

AZ-900 Azure Fundamentals Resources

Claudio Altamura — Wed, 25 May 2022 09:45:47 +0000

My curated list

There are plenty of resources out there to help you study for the AZ-900 exam. The exam is for candidates who are just beginning to work with cloud-based solutions and services.

It’s an opportunity to gather knowledge of cloud concepts, services, workloads, security, privacy, pricing and support. Here comes my list:

Cloud Concepts

Benefits
https://docs.microsoft.com/en-us/learn/modules/fundamental-azure-concepts/benefits-of-cloud-computing

Elastic
https://azure.microsoft.com/en-us/overview/what-is-elastic-computing/

Consumption and fixed cost models
https://docs.microsoft.com/en-us/azure/architecture/framework/cost/design-price

Shared responsibility
https://docs.microsoft.com/en-us/azure/security/fundamentals/shared-responsibility

Cloud Computing
https://docs.microsoft.com/en-us/learn/modules/fundamental-azure-concepts/types-of-cloud-computing

IAAS
https://azure.microsoft.com/en-us/overview/what-is-iaas/

PAAS
https://azure.microsoft.com/en-us/overview/what-is-paas/

SAAS
https://azure.microsoft.com/en-us/overview/what-is-saas/

Cloud Models
https://azure.microsoft.com/en-us/overview/what-are-private-public-hybrid-clouds/

Public cloud
https://azure.microsoft.com/en-gb/overview/what-is-a-public-cloud/

Geographies
https://azure.microsoft.com/en-us/global-infrastructure/geographies/#overview

Region and availability zones
https://docs.microsoft.com/en-us/learn/modules/azure-architecture-fundamentals/regions-availability-zones

Compute
https://azure.microsoft.com/en-us/product-categories/compute/

Virtual machines
https://docs.microsoft.com/en-us/learn/modules/azure-compute-fundamentals/azure-virtual-machines

Serverless
https://docs.microsoft.com/en-us/learn/modules/azure-compute-fundamentals/azure-functions

Previews
https://azure.microsoft.com/en-us/support/legal/preview-supplemental-terms/

Pricing
https://docs.microsoft.com/en-us/learn/modules/plan-manage-azure-costs/ https://azure.microsoft.com/en-us/pricing/calculator/
https://azure.microsoft.com/en-us/pricing/tco/calculator/

Core Solutions

Big Data
https://docs.microsoft.com/en-us/azure/architecture/guide/architecture-styles/big-data

IoT
https://docs.microsoft.com/en-us/azure/iot-fundamentals/iot-introduction

Cognitive Services
https://azure.microsoft.com/en-us/services/cognitive-services/

Goverance

Strategy
https://docs.microsoft.com/en-us/learn/modules/build-cloud-governance-strategy-azure/

Resource Groups
https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview#resource-groups

Azure Management Groups
https://docs.microsoft.com/en-us/azure/governance/management-groups/overview

Policy
https://docs.microsoft.com/en-us/azure/governance/policy/overview

Blueprints
https://docs.microsoft.com/en-us/learn/modules/build-cloud-governance-strategy-azure/8-govern-subscriptions-azure-blueprints

Identity & Access

Azure AD
https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-whatis

SSO
https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/what-is-single-sign-on

MFA
https://docs.microsoft.com/en-us/azure/active-directory/authentication/concept-mfa-howitworks

Management Tools

Azure Advisor
https://docs.microsoft.com/en-us/azure/advisor/

Azure Cloud Shell
https://docs.microsoft.com/en-us/azure/cloud-shell/overview

Azure Cost Management
https://docs.microsoft.com/en-us/learn/paths/az-900-describe-azure-cost-management-service-level-agreements/

Azure Key Vault
https://docs.microsoft.com/en-us/azure/key-vault/

Azure Monitor
https://docs.microsoft.com/en-us/azure/azure-monitor/overview

Azure Resource Manager
https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview

Azure Service Health
https://docs.microsoft.com/en-us/azure/service-health/overview

Azure Service Trust
https://servicetrust.microsoft.com/

Network & Security

Network
https://docs.microsoft.com/en-us/azure/security/fundamentals/network-overview

CDN
https://docs.microsoft.com/en-us/azure/cdn/cdn-overview

Load Balancing
https://docs.microsoft.com/en-us/azure/architecture/guide/technology-choices/load-balancing-overview

Defense in depth
https://docs.microsoft.com/en-us/learn/modules/secure-network-connectivity-azure/2-what-is-defense-in-depth

Perimeter networks
https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/perimeter-networks

VPN
https://docs.microsoft.com/en-us/learn/modules/azure-networking-fundamentals/express-route-fundamentals

Network Security
https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/considerations/networking-options

Network Security Groups
https://docs.microsoft.com/en-us/azure/virtual-network/network-security-groups-overview

DDoS
https://docs.microsoft.com/en-us/azure/ddos-protection/ddos-protection-overview

I hope this list helps you. 😀

How to test a Quarkus GraphQL API

Claudio Altamura — Fri, 01 Oct 2021 14:43:38 +0000

With curl, the GraphQL tool, insomnia and Rest-assured

In the previous article I described the Quarkus GraphQL support and we discussed some GraphQL topics. Now I’ll show you how to test your GraphQL API with curl, the GraphQL tool, insomnia and Rest-assured. As an example I use my superhero project from my last article, which can be found on GitHub for you to run and play around with.

curl

If you would like to try the GraphQL API by yourself, start the Quarkus Project with mvn quarkus:dev and write the following:

    curl --request POST \
    --url http://localhost:8080/graphql \
    --header 'Content-Type: application/json' \
    --data '{"query":"{allCities{name}}"}'

That is quite simple. All we’ll need is to create a JSON payload, e.g. with a single element query with our query as its value. And as a result, you get this.

{"data":{"allCities":[{"name":"Gotham City"},{"name":"New York City"}]}}

GraphQL Tool

Let's move on to the GraphQL tool. You can do the same query with the Quarkus GraphQL tool. Just enter http://localhost:8080/q/graphql-ui/. On the left side type in the query. Press the button with the triangle, and then you can see the result on the right side.

Insomnia

I think it's pretty cool that you can test both REST and GraphQL APIs with Insomnia. To create a GraphQL query, you have to switch from Body to GraphQL on the far left. And that's it.

Rest-assured

If you want to write automated tests, you could use Rest-Assured as we have already discovered. For the sake of completeness, I repeat the example from the last article. The response is plain JSON, so we can assert on the data returned by the API in the exact same manner with REST Assured as with REST APIs.

@QuarkusTest
public class SuperheroTest {

    @Test
    void allCities() {
        final Response response = given()
                .contentType(ContentType.JSON)
                .body("{\"query\":\"{\\n allCities{\\n name\\n}\\n}\"}")
                .when()
                .post("/graphql")
                .then()
                    .assertThat()
                    .statusCode(200)
                .and()
                    .extract()
                    .response();

        final List<City> allCities = response.jsonPath().getList("data.allCities", City.class);
        assertThat(allCities)
                .isNotEmpty()
                .hasSize(2)
                .extracting(City::getName)
                .contains("Gotham City", "New York City");
    }

}

Conclusion

As you have seen in this article, it is quite simple to test a GraphQL API. You can use curl for a quick check or the GraphQL Tool / Insomnia if you need more convenience. It's even possible to use REST Assured to write automated tests because the response is pure JSON.

Links
Github https://github.com/claudioaltamura/quarkus-graphql-superheroes
Quarkus SmallRye GraphQL https://quarkus.io/guides/smallrye-graphql
Insomnia https://insomnia.rest/
Rest-assured https://rest-assured.io/

GraphQL APIs with Quarkus

Claudio Altamura — Mon, 30 Aug 2021 07:54:35 +0000

A query language for your API

In this article, I'll show you Quarkus GraphQL support. As an example, I use the Superheroes application from my previous articles. We will discuss some GraphQL topics.

Code, dependencies and model

The source code for this app is available on Github. If you like, you can try the examples by yourself. As dependencies, I included e.g. SmallRye GraphQL and lombok. Here you can have a detailed look at the pom.xml file.

Quarkus helps you to create GraphQL APIs. The GraphQL schema is going to be generated. You just have to define your model. Here I show you as an example the Superhero data transfer object. I use DTOs to expose data from an API. Lombok @Data takes care of getter, setter, toString, and the equals and hashCode methods.

import lombok.Data;

@Data
@FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)
public class Superhero {

    String name;
    City city;

}

Fetching data

To query all cities you just have to send a command like this to the GraphiQL UI http://localhost:8080/q/graphql-ui/ .

{
    allCities {
        name
    }
}

And with GraphQL it's quite easy to fetch object graphs. For example, we could query a city with their superheroes like this.

query getCity {
     city(cityId: 0) {
         name
         symbol
         superheroes {
             name
         }
     }
 }

Resolver and mutations on the server-side

A resolver is responsible for defining queries. All Queries are located in SuperheroResolver.

@GraphQLApi
public class SuperheroResolver {

    @Inject
    SuperheroService superheroService;

    @Query("allCities")
    @Description("Get all cities.")
    public List<City> getAllCities() {
        return superheroService.getAllCities();
    }
 ...
}

I have separated the mutations from the queries. Mutations are write operations like create, update or delete. Here I show the create() method from SuperheroMutation with SuperheroInput as an input object.

@GraphQLApi
public class SuperheroMutation {

    @Inject
    SuperheroService superheroService;

    @Mutation
    public Superhero createSuperhero(@Name("superhero") SuperheroInput superheroInput) {
        var superhero = new Superhero(superheroInput.getName(), superheroInput.getCity());
        superheroService.addSuperhero(superhero);
        return superhero;
    }
...
}

Testing GraphQL APIs

It's pretty cool that Quarkus automatically generates a GraphQL schema based on your source code. To display the schema, just invoke http://localhost:8080/graphql/schema.graphql . Here I want to show you quickly, how to write automated tests. How do we test a GraphQL API? Here comes Rest-Assured to the rescue. You can write tests in a manner as you already know from REST.

@QuarkusTest
public class SuperheroTest {

    @Test
    void allCities() {
        final Response response = given()
                .contentType(ContentType.JSON)
                .body("{\"query\":\"{\\n allCities{\\n name\\n}\\n}\"}")
                .when()
                .post("/graphql")
                .then()
                    .assertThat()
                    .statusCode(200)
                .and()
                    .extract()
                    .response();

        final List<City> allCities = response.jsonPath().getList("data.allCities", City.class);
        assertThat(allCities)
                .isNotEmpty()
                .hasSize(2)
                .extracting(City::getName)
                .contains("Gotham City", "New York City");
    }

}

Conclusion

I like the GraphQL support from Quarkus. It's great that the GraphQL schema is generated automatically through code and annotations. In the next part I'll show you how to test you GraphQL API with curl, the GraphiQL tool and insomnia.

Photo by Raphaël Biscaldi on Unsplash

Links
https://github.com/claudioaltamura/quarkus-graphql-superheroes

https://quarkus.io/guides/smallrye-graphql

https://rest-assured.io/

Document your database

Claudio Altamura — Thu, 31 Dec 2020 19:03:01 +0000

Simply and easily with SchemaSpy

It has never been easier to document you db. SchemaSpy analyzes your database with tables, columns, types and indexes. It even creates diagrams with relationships of your existing database.

The installation is super easy. You just have to download SchemaSpy https://github.com/schemaspy/schemaspy/releases and your database driver. Even Graphviz is no longer required. The configuration is really simple. Here I show a config.

You run the tool with "java -jar schemaspy-6.1.0.jar -configFile config.properties". Then you get a HTML documenation and the diagrams look like this.

And a really cool trick is to integrate SchemaSpy in your CI/CD pipeline.

I really like this tool.

Writing key values from Java to Consul

Claudio Altamura — Fri, 11 Dec 2020 13:23:37 +0000

How to write key values to Consul

In the first example we are going to use the HTTP API directly, in the second one we are going to use the Java Consul API ecwid. On Github you'll find all the examples. So, let's start.

HTTP API
In this example we store the value "buon giorno" with the key "message". And all you have to do is a REST PUT operation with v1/kv as a path. Here, Consul is reachable at http://127.0.0.1:8500. That's it.

var value = "buon giorno";
var keyValuePath = "/config/consul-example/greetings/message";
var resourceUrl = "http://127.0.0.1:8500/v1/kv" + keyValuePath;

HttpRequest request = HttpRequest.newBuilder()
  .uri(new URI(resourceUrl))
  .PUT(HttpRequest.BodyPublishers.ofString(value))
  .build();

HttpClient
  .newBuilder()
  .build()
  .send(request, HttpResponse.BodyHandlers.ofString());

Java Consul API
The library is quite easy. First you have to create a ConsulClient with an URL. You use that ConsulClient for reading and writing. It's just set* (with a key and the value) and get* methods. With the getKVValue() you get a Response instance. And for the real value you have to call getDecodedValue(). :-)

ConsulClient consulClient = new ConsulClient("http://127.0.0.1:8500");

consulClient.setKVValue("/config/blueprint/greetings/note", "hello");

Response<GetValue> response = consulClient.getKVValue("/config/blueprint/greetings/note");

System.out.println("value: " + response.getValue().getDecodedValue());

Links
https://www.consul.io/api-docs#http-methods
https://github.com/Ecwid/consul-api