DEV Community: Manuel Doncel Martos

Practicing Basic Concepts On Web Security

Manuel Doncel Martos — Wed, 08 Apr 2026 17:39:56 +0000

Building (and Breaking) a Vulnerable Web App in Go + Vue.js

As developers, we often learn best by doing, and in cybersecurity, that means not just building secure systems, but also understanding how they break.

During the last months, I was on charge of explaining some of the OWASP vulnerabilities to my team, and for that I created a vulnerable web application using Go (backend) and Vue.js (frontend), designed to demonstrate some of the most common and dangerous web vulnerabilities.

The project is available here: https://github.com/manuelarte/gowasp
The README includes a step-by-step hands-on exploitation guide.

In this post, I’ll walk through the key vulnerabilities implemented in the app and how an attacker can exploit them.

🧨 1. SQL Injection

The vulnerability

SQL Injection occurs when user input is directly concatenated into SQL queries without proper sanitization or parameterization.

A typical vulnerable pattern looks like:

query := "SELECT * FROM users WHERE email = '" + email + "' AND password = '" + password + "'"

Exploitation

An attacker can bypass authentication by injecting SQL logic:

email: admin' --
password: anything

This turns the query into:

SELECT * FROM users WHERE email = 'admin' --' AND password = 'anything'

The password check is commented out, granting access without valid credentials.

In the vulnerable application, you can practice this vulnerability and try to log in without knowing the password.

Takeaway

Always use prepared statements or ORM parameter binding. Never trust raw user input.

🧬 2. Mass Assignment

The vulnerability

Mass assignment happens when user-controlled input is directly bound to a struct or model without filtering allowed fields.

Example:

json.NewDecoder(r.Body).Decode(&user)

If the User struct includes sensitive fields like isAdmin, an attacker can modify them.

Exploitation

A malicious request:

{
  "email": "attacker@example.com",
  "password": "123456",
  "isAdmin": true
}

If the backend doesn’t explicitly restrict fields, the attacker becomes an admin by assigning himself as admin.

Takeaway

Use DTOs (Data Transfer Objects) or explicit field mapping. Never bind request bodies directly to domain models.

🔁 3. CSRF (Cross-Site Request Forgery)

The vulnerability

CSRF occurs when authenticated users unknowingly perform actions triggered by malicious websites.

If your app relies only on cookies for authentication and lacks CSRF protection, it's vulnerable.

Exploitation

An attacker can craft a hidden form:

<form action="https://yourapp.com/api/delete-account" method="POST">
  <input type="submit" />
</form>

<script>
  document.forms[0].submit();
</script>

If the victim is logged in, their browser will send the request with session cookies—deleting their account without consent.

Takeaway

Use CSRF tokens and validate them server-side. SameSite cookies help, but are not enough alone.

🧩 4. HTML Template Injection

The vulnerability

When user input is rendered into templates without proper escaping, attackers can inject malicious expressions.

In Go templates, unsafe usage might look like:

tmpl.Execute(w, userInput)

And in VueJS it can be used with v-html.

Exploitation

An attacker injects template syntax in part that renders user input.

In some engines, this can lead to:

Data leakage
Server-side execution
XSS (if rendered in browser)

Takeaway

Always treat user input as untrusted. Use proper escaping and avoid rendering raw input in templates.

Why This Project Matters

Modern frameworks make it easier to build applications—but they don’t make them automatically secure. These vulnerabilities are still incredibly common in real-world systems.

By intentionally building insecure features, this project helps you:

Understand how attacks actually work
Recognize insecure coding patterns
Learn how to defend against them effectively

🛠️ Try It Yourself

The repository includes a full walkthrough so you can:

Run the vulnerable app locally
Exploit each vulnerability step by step
Understand the impact in a safe environment

👉 https://github.com/manuelarte/gowasp

Final Comments

Security is not a feature you apply from the beginning.

If you can break your own system, you’re already one step closer to building something resilient.

And if you haven’t tried breaking it yet… someone else eventually will.

What developers don't get about Idempotence

Manuel Doncel Martos — Wed, 18 Feb 2026 16:38:03 +0000

❓Quick question:

Is a DELETE endpoint that returns 404 on subsequent calls idempotent?

If you said 'no' because the response changed, this article is for you.

Idempotence is a concept that is often misunderstood, sometimes even by developers with many years of experience.

What is Idempotence

If we take the Wikipedia definition:

Idempotence is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application.

So as we can see, it's originally a mathematical concept that got translated to Computer Science.

In Computer Science, the term idempotence I like to describe it as:

Idempotence in computer science is the property of an operation whereby it can be applied multiple times without changing the result beyond the initial application

Example GET operation

Normally, a GET operation is idempotent, since it does not imply any change in the database. So, for example, you can have an endpoint like:

/api/v1/users

And it does not matter how many times you call it, it will return the same output and produce no side effect.

POST, PUT, PATCH and DELETE operations

This is where the confusion comes from. People by default think that POST, PUT, and PATCH endpoints are not idempotent by definition, and the answer is that it depends on the actual implementation of the endpoints.

POST operations

Let's look for example the case of a POST endpoint to create Users.

Imagine that we have the following model:

class User {
  final UUID id;
  final String username;
}

And we call the endpoint:

> POST api/v1/users

{
  "username": "manuelarte"
}

Getting a response:

200 OK
{
  "id": "f2f7734c-1082-43cf-9b66-9161349ef154",
  "username": "manuelarte"
}

❓Is this endpoint idempotent?

With this information alone, we cannot determine it yet.

Scenario A: A new user is created

If we call it again with the same input and we get:

200 OK
{
  "id": "c6fab354-c559-460b-a66c-5d0bad8f6aba",
  "username": "manuelarte"
}

Then the endpoint is definitely not idempotent❌, since it is creating new users for each request with the same data.

Scenario B: Same response as first response

And, what happens if we call the endpoint again with the same data and the response is the same as in the first call:

200 OK
{
  "id": "c6fab354-c559-460b-a66c-5d0bad8f6aba",
  "username": "manuelarte"
}

Then, ✅the endpoint is idempotent, because it's not creating a new entry in the database, and in this case is returning the already existing entry.

So, it does not matter how many times you call this endpoint with this data, the state remains the same.

This is the scenario that most people understand for idempotence. If you do multiple request with the same data, you always get the same response, same HTTP response code and same body.

Scenario C: Consecutive calls returns different response

But, let's imagine that the endpoint returns the following:

400 Bad Request
{
  "code": "USER_CREATED",
  "message": "user already created"
}

So now, instead of 200, it is returning 400, and explaining that there is already a user with that username created.

❓Do you think that this endpoint is, then, idempotent?

And the answer is (and this is where many senior developers and/or architects get idempotence wrong) that this implementation is also idempotent, because the second and subsequent calls do not change state. In this case, with only one user created.

So idempotence is about the final state in the database, and not about the HTTP verb or HTTP response code.

DELETE endpoints

To clarify more, let's put another example, this time using a DELETE endpoint:

DELETE /api/v1/users/{id}

If we call this endpoint with the user id, then this endpoint is idempotent independently of the response code, because after the first successful deletion, the resource no longer exists, and further calls do not change the state.

So after that initial call, next calls can have outputs like NO CONTENT 204 or NOT FOUND 404 and the endpoint is still idempotent.

But you could have an endpoint like this

DELETE /api/v1/users/last

That would delete the latest user created, and even that it could potentially return, e.g. NO CONTENT 204 for every call, the endpoint would not be idempotent.

So, as an example, each call changes which user is considered "last". The first call deletes user 5, the second deletes user 4, and so on. The state changes with each call.

Summary and takeaways

Hopefully you are able to understand that idempotence is about consecutive calls with the same data leads to no change in the state.

Understanding that idempotence is about state, not responses, is crucial for:

API Design: Building robust systems that handle retries safely
Client Implementation: Knowing how to handle different response codes
Contract Testing: Writing accurate tests for API behavior

Next time you're designing or consuming an API, remember:

idempotence = State doesn't change after the first request
HTTP methods suggest idempotence, but implementation guarantees it

idempotence isn't about what the server says—it's about what the server does.

For more references check RFC-9110, and how to implement idempotence with headers

[Boost]

Manuel Doncel Martos — Mon, 26 Jan 2026 18:30:12 +0000

Elegant Domain-Driven Design objects in Go

Manuel Doncel Martos ・ Jan 19

#ddd #go #entity #valueobjects

go-kata 01/01-concurrent-aggregator

Manuel Doncel Martos — Mon, 26 Jan 2026 10:00:09 +0000

A few weeks ago I discovered this GitHub repository go-kata, containing some Go exercises that encourage to write idiomatic Go. What caught my attention was the fact that they come with no solutions, just you, the problem, and your Go skills.

The repository quickly gained traction, and got more than 1k stars⭐ and was mentioned in several social networks, e.g. X.

I decided to tackle these problems myself and share my solutions in my own fork, hoping to inspire people to try and to refine my approach through community feedback.

01-context-cancellation-concurrency/01-concurrent-aggregator

The Problem

The challenge is straightforward but captures a common real-world scenario:

Call two services concurrently, Profile and Order, combine their outputs into a single string like
"User: Alice | Orders: 5", and handle failures gracefully.
If either service call fails, the entire operation must be interrupted immediately.

A more detailed description of the requirements can be found in the README.md.

Implementing The Services

Let's start implementing the services. The goal is they can be configurable in a way that they can either return the actual result, or an error, and also how long does it take to get that response.

So we could have something like:

✅ Both services succeed within timeout
⏱️ Both services timeout
❌ One service fails while the other succeeds
🔄 Context cancellation propagates correctly

For that, and without entering in too much details, I created a mock service that I can configure the output and the time.

type (
    Service[T any] struct {
        Response Response[T]
    }

    Response[T any] struct {
        Sleep time.Duration
        Val   T
        Err   error
    }
)

func (s Service[T]) GetResponse(ctx context.Context) (T, error) {
    t := new(T)

    select {
        case <-time.After(s.Response.Sleep):
            return s.Response.Val, s.Response.Err
        case <-ctx.Done():
            return *t, ctx.Err()
    }
}

Then I created the profile.Service and order.Service using that mock.

In that way, I can configure the two services to cover those scenarios we mentioned above, e.g:

Profile and order services returns the successful response on time:

timeout := 2*time.Second
ps := profile.NewMockService(profileSuccessResponse(time.Millisecond))
os := order.NewMockService(orderSuccessResponse(time.Millisecond))

Profile and order services returns the successful response not on time:

timeout := 2*time.Second
ps := profile.NewMockService(profileSuccessResponse(3*time.Second))
os := order.NewMockService(orderSuccessResponse(3*time.Second))

Profile service returns a successful response on time, but order service returns an error.

timeout := 2*time.Second
ps := profile.NewMockService(profileSuccessResponse(time.Millisecond))
os := order.NewMockService(errorOrderResponse (time.Millisecond))

Other combinations...

Implementing The Aggregator

The goal of the aggregator is to call those two services concurrently, and stop as soon as one of the queries fail.
You must use golang.org/x/sync/errgroup.

First let's define the Aggregator, we need the two services and a timeout:

type UserAggregator struct {
    profileService profile.Service
    ordersService  order.Service
    timeout        time.Duration
}

The go-kata also mentions that the Aggregator needs to be configurable using the Functional Options Pattern, so then we can define the constructor like this:

func New(ps profile.Service, os order.Service, options ...func(*UserAggregator)) UserAggregator {
    ua := &UserAggregator{
        profileService: ps,
        ordersService:  os,
    }
    for _, option := range options {
        option(ua)
    }

    return *ua
}

And then, finally the actual Aggregate implementation. We need to declare a context.Context using the timeout passed as a struct field, and then use:

g, ctx := errgroup.WithContext(ctx)
g.Go(...

To concurrently query the two services.

func (ua UserAggregator) Aggregate(id int) (string, error) {
    ctx, cancel := context.WithTimeout(context.Background(), ua.timeout)
    defer cancel()

    var (
        user       string
        orderValue string
    )

    g, ctx := errgroup.WithContext(ctx)
    g.Go(func() error {
        u, err := ua.profileService.GetProfile(ctx, id)
        if err != nil {
            return err
        }

            user = u.Name

            return nil
    })
    g.Go(func() error {
        o, err := ua.ordersService.GetOrder(ctx, id)
        if err != nil {
            return err
        }

        orderValue = o.Order

        return nil
    })

    err := g.Wait()
    if err != nil {
        return "", err
    }

    return fmt.Sprintf("User: %s | Orders: %s", user, orderValue), nil
}

What's Next?

I'm working through more go-kata problems and publishing solutions in my fork.
I'd love to hear your feedback:

Would you solve this differently?
Are there edge cases I'm missing?
What Go patterns would you apply?

Elegant Domain-Driven Design objects in Go

Manuel Doncel Martos — Mon, 19 Jan 2026 05:41:09 +0000

❓How do you define in Go your domain objects?

Go isn't your typical object-oriented language. When you try to implement Domain-Driven Design (DDD) concepts like Entities and Value Objects it can feel that you are fighting against the language.

In this article, I'll share practical patterns I've used to implement DDD concepts in Go. We'll focus on making your domain code expressive, type-safe, and maintainable.

⚠️This is an opinionated article that hopefully helps you to implement better and more elegant structs.
Aggregates are left out on purpose.

Our Domain: Coffee Shop Loyalty Program

Let's come up with an easy example so we can focus on how to properly define DDD structs.

Problem Space

"How do we encourage customers to return to our coffee shop by rewarding repeat purchases?"

Core Problems:

Customers buy coffee.
We want to give them points for each purchase.
Points expire after 30 days.
We can show a leaderboard and give rewards like free coffee.

Solution Space

After several collaborations/iterations with the domain experts, we've identified:

An entity Customer, that contains customer's info and their coffee orders.
A value object CoffeeOrder, that contains information about the order.

Let's start implementing the CoffeeOrder first.

Initial Implementation Attempt

Value Objects

Value objects are immutable objects representing descriptive aspects of a domain, defined solely by its attributes (values) rather than a unique identity.

type CoffeeOrder struct {
  // Size of the ordered coffee.
  Size string
  // OrderBy user id that ordered the coffee.
  OrderBy int
  // OrderTime time when the ordered happened.
  OrderTime time.Time
}

As we can see, there is not anything like ID, or CoffeeOrderID.

Entities

Entities are objects defined by their unique identity, not just its attributes, possessing a lifecycle and continuity through changes in its state.

type Customer struct {
  // ID of the customer.
  ID int
  // Name of the customer.
  Name string
  // CoffeeOrders the coffee orders of this customer.
  CoffeeOrders []CoffeeOrder
}

Then, we can implement the business logic by asking the Customer's for their points at a particular moment in time, with something like:

// PointsAt returns the points of a customer at a moment in time.
func (c *Customer) PointsAt(ref time.Time) int{
  points := 0
  for _, co := range c.CoffeeOrders {
    points += co.Points(ref)
  }

  return points
}

Despite this can look OK, there are many things that can be improved.

Levelling Up: Making Our Domain More Robust

Immutability

An entity needs to mutate, but a value object needs to be immutable. The current implementation does not guarantee immutability for the CoffeeOrder struct.
In fact, this is a concept that it's not natural in Go, and here is an example in which we need to fight against the language.

❓How To Achieve Immutability

One of the most obvious things to do is to use non-pointer receivers in the struct's methods, but fields can't be exported either, because if not, they can be modified like so:

co.OrderBy = 5

Because field can't be exported, then we need to add a constructor.

🎓 There are no constructor in Go, but people call constructors to functions that starts with New, or Must and returns either the struct, or the struct and an error.

So we can have something like:

type CoffeeOrder struct {
  // size of the ordered coffee.
  size string
  // orderBy user id that ordered the coffee.
  orderBy int
  // orderTime time when the ordered happened.
  orderTime time.Time
}

func NewCoffeeOrder(size string, orderBy int, orderTime time.Time) CoffeeOrder {
  return CoffeeOrder{
    size:      size,
    orderBy:   orderBy,
    orderTime: orderTime,
  }
}

In this case this is enough, but we need to make sure that each field is also immutable. As an example, a value object that uses a slice or a map as an input parameter, needs to make sure that that can't be modified externally (defensive copy).

❓ Is It Now Immutable and Completely Ready?

The answer is not, since the struct is exported, we could skip the instantiation of the struct using the constructor and directly do:

co := CoffeeOrder{}

Creating a zero-value struct that is clearly invalid.
To avoid that you could create an interface like:

type (
  CoffeeOrder interface {
    Size() CoffeeSize
    OrderBy() CustomerID
    OrderTime() time.Time
    Points(ref time.Time) CoffeePoints
    x() // method to make sure interface implementation is only defined in this package.
  }

  type coffeeOrder struct {
    // size of the ordered coffee.
    size CoffeeSize
    // orderBy user id that ordered the coffee.
    orderBy CustomerID
    // orderTime time when the ordered happened.
    orderTime time.Time
  }
)

Then the constructor would instantiate coffeeOrder but returns CoffeeOrder.

Key concepts:

Interface hides implementation details.
Constructor validates business rules.
No exported fields prevent direct mutation.
Value receivers (CoffeeOrder, not coffeeOrder) prevent modification.

Using Domain-Specific Types, Not Primitives

Go has the option to create custom types with Type Definition, this allows us to leverage the behaviour of primitive types to give more meaning to our fields.

As an example, we could define a type like:

type CustomerID int

And use it in both our structs, giving more meaning to the field. This custom type allows us to define functions that accept a CustomerID not just a regular int.

And the same goes with the coffee size, allowing us to add new methods to this new type like validating the value.

type CoffeeSize string

// IsValid returns whether the coffee size has a valid value or not.
func (cs CoffeeSize) IsValid() bool {
  switch cs {
    case "small", "medium", "large":
      return true
    default:
      return false
  }
}

💡In general, I recommend to define new types over primitive types, since they give more domain meaning to your struct definitions and function/methods. And allows you to create custom methods that enhance their functionality in a localized way.

Creating Rich Domain Errors

Now, we can change our CoffeeOrder constructor like this:

func NewCoffeeOrder(size CoffeeSize, orderBy CustomerID, orderTime time.Time) (CoffeeOrder, error) {
  if !size.IsValid() {
    return CoffeeOrder{}, errors.New("invalid Coffee Size")
  }
  return coffeeOrder{
    size:      size,
    orderBy:   orderBy,
    orderTime: orderTime,
  }, nil
}

We are checking whether the value given by the user is a correct coffee size or not, and if not we return an error.

In this case we are creating an error directly, but the error itself does not contain any meaning, just a string with the error message.

I also recommend creating custom errors that give enough context to the caller to understand what happened.
We could create something like:

var _ error = new(WrongCoffeeSizeError)

type WrongCoffeeSizeError struct {
  Size string
}

func (e WrongCoffeeSizeError) Error() string {
  return fmt.Sprintf("invalid coffee size: %s", e.Size)
}

And then, return it like:

if !size.IsValid() {
  return CoffeeOrder{}, WrongCoffeeSizeError{Size: string(size)}
}

Service Layer

Services are used in DDD to orchestrate business operations that are above the domain. In this case, we could create a service to get all the CoffeeOrders in the last 30 days, then get all the Customer's of those orders and sort them by points to get the leaderboard.

Practical Tips

Linting

Some of these practices can be enforced with a linter. There are many linters available in Go, but not one specialized for DDD, so I decided to create one that I use in my projects to make sure that I check patterns like:

Immutability for Value objects.
Custom types over primitives for Entities.
Pointer and non-pointer receivers for Entities and Value objects.
No errors.New used in returning a method call.

It's still under heavy development, but hopefully it can help you to create more elegant objects.
Here is the link to the repository godddlint in case you are interested.

Summary

In this article we covered several DDD concepts but also other concepts like:

Immutability.
Create domain-specific types for compile-time safety.
Defining new domain errors.

What patterns have you found effective for DDD in Go? Share your experiences in the comments!

Pagination in GORM

Manuel Doncel Martos — Mon, 23 Jun 2025 20:58:51 +0000

Gorm is the most used ORM package in Go, but, despite that, it is lacking some “basic” functionality.

One of those lacking features is Pagination.

Pagination is an essential feature for managing large datasets in web applications. It is an approach to limit and display part of the total data in a database, so then not all the table needs to be retrieved in one “go”.

While GORM provides documentation on how to use pagination using scopes, it leaves room for improvement in flexibility and usability.

Here, I am going to explain an alternative to scopes for pagination, using GORM’s Clauses.

Pagination Using Scopes

GORM’s documentation introduces Scopes as a way to re-use common code. In the documentation example, we can see that they define a pagination scope function similar to this:

func Paginate(page, pageSize int) func(db *gorm.DB) *gorm.DB {
  return func (db *gorm.DB) *gorm.DB {
    // validate page and pageSize
    ...
    offset := (page - 1) * pageSize
    return db.Offset(offset).Limit(pageSize)
  }
}

page := 0
pageSize := 10
db.Scopes(Paginate(page, pageSize)).Find(&users)

So, in order to apply pagination, we need to use the code

db.Scopes(Paginate(page, pageSize))…

Pagination Using Clauses

A different and, arguably, more elegant approach is to use GORM Clauses, this approach is a bit different to using Scopes, since Clauses are on charge of modifying the database queries, in particular, the WHERE clause.

Let’s start by defining the pagination struct

type Pagination struct {
 page          int
 pageSize      int
}

func (p *Pagination) GetPage() int {
 return p.page
}
func (p *Pagination) GetPageSize() int {
 return p.pageSize
}

And then, let’s implement the two interfaces needed to use this struct in a GORM clause function:

clause.Expression
gorm.StatementModifier

So the struct looks like this:

func (p *Pagination) ModifyStatement(stm *gorm.Statement) {
  // We modify statement to add the pagination
  db := stm.DB
  stm.DB.Limit(p.size).Offset((p.page - 1) * p.pageSize)
}

func (p *Pagination) Build(_ clause.Builder) {
  // The Build method is left empty since pagination does not require any additional SQL clauses.
}

After that, you can use pagination as follows:

pagination := Pagination{
  page: 0,
  pageSize: 10,
}
db.Clauses(&pagination).Find(&users)

To make this approach reusable and enhance its capabilities, I developed PaGorminator — a library that uses this feature for pagination, while adding other features like unpaged requests and automatic metadata population like total number of pages, and total count.

To use it, do as follows:

// Add plugin
_ = db.Use(pagorminator.PaGorminator{})
...
pageRequest, _ := pagorminator.PageRequest(0, 10)
db.Clauses(pageRequest).Find(&users)
// this will apply pagination, and also populate pageRequest with:
// - the total number of pages
// - total count

Introducing GitHub Kudos

Manuel Doncel Martos — Thu, 23 Jan 2025 20:57:09 +0000

The open-source community is built on collaboration, recognition, and support. If you are familiar with platforms like GitHub, you know how challenging it can be to express who you think they are talented developers.
We all, also, know how much a word of encouragement can mean to someone who has worked tirelessly on their code or projects.

That’s why I created GitHub Kudos, a simple way to give shoutouts and kudos to other GitHub users.

What is GitHub Kudos

GitHub Kudos is an app that allows you to generate images with the recommendation for GitHub users. These images feature the user’s profile avatar and a recommendation message written by you. They can be used in GitHub profiles, personal websites, blogs, or anywhere you want either show who you recommend, or who is recommending you.

How Does It Work

It’s very simple:

Create a repository in your GitHub account called github-kudos. (e.g., manuelarte/github-kudos)
Inside this repository, create a file named after the GitHub username of the person you want to recommend (e.g., octocat.md).
Write your recommendation in plain text inside the file.
After you push the file, the image can be visualized at https://github.com/{{your-github-username}}/kudos/{{other-github-username}}. (e.g. https://github-kudos.com/manuelarte/kudos/octocat)

I created a GitHub template that you can use as reference at https://github.com/manuelarte/github-kudos-template/

Once people recommend you, you have a ready-to-use image to share on your GitHub profile, website, or social media!

Why Did I Build This

I’ve always believed in the power of recognition. As developers, we often rely on each other’s work, whether it’s an open-source library, a piece of advice, or a helpful comment in an issue. However, we rarely take a moment to publicly acknowledge those contributions. GitHub Kudos aims to change that by making it easy to celebrate others’ efforts.

I also believe that a GitHub profile, in which you showcase your projects, plus you show how people see feel when working with you, can help in the always tedious process of looking for a new job.

Key Features

Personalized Recommendations: You decide what to write about someone, making each image unique and meaningful, with the possibility of changing it at any time.
Visual Appeal: The images are designed to stand out, making them perfect for GitHub READMEs or social media.
Open and free: Anyone can create a github-kudos repository and start giving kudos to others.

Join The Kudos Movement

Not only does it build a more supportive community, but it also encourages people to continue creating, sharing, and collaborating.

If this resonates with you, give GitHub Kudos a try and start spreading positivity today.

If you want to see how it looks, check my profile: https://github.com/manuelarte#-people-i-recommend.

I’d love to hear your thoughts, feedback, or ideas to improve GitHub Kudos.

Simplify Your REST API Responses with Milogo for Gin-Gonic

Manuel Doncel Martos — Mon, 18 Nov 2024 16:54:24 +0000

Gin-Gonic Middleware that implements fields selection pattern

At my company we use Go to build internal tools. Recently I worked in a REST API using gin-gonic, that required displaying a lot of data across many endpoints.

One must have feature in this type of scenario, is pagination, but and often overlooked pattern is partial response (a.k.a field selection). Which is also a very nice addition to filter out the amount of data in the responses of your web server.

What’s field selection?

Let us first make it clear what I mean with a field selection. Imagine that you have the following endpoint:

// > GET /api/products
[
  {
    "id": 1,
    "createdAt": "2024-18-11",
    "updatedAt": "2024-18-11",
    "code": "1",
    "price": {
      "amount": 100,
      "currency": "EUR"
    },
    "manufacturedBy": "myshop",
    "stock": 552,
    ...
  },
  ...
]

Using partial responses, clients can filter the output with a fields query parameter, e.g.

// > GET /api/products?fields=code,price
[
  {
    "code": "1",
    "price": {
      "amount": 100,
      "currency": "EUR"
    }
  },
  ...
]

Only the fields declared in the query parameter are returned. Reducing the payload size and saving bandwidth.

Introducing Milogo

I could not find any implementation available for this pattern, so I decided to create it myself, and that is how Milogo was born.
Milogo is a Gin middleware that processes API responses, filters out fields specified in the fields query parameter, and return only the requested data.

Some of the main features available:

Support for json objects and json arrays.
So Milogo can filter fields for JSON responses that starts with an array of items or just with one single item.
Support for filtering out fields in nested json objects.
Milogo also supports filtering nested JSON objects with the following format e.g. code,price(amount)
Support for json wrapped in another json.
Sometimes the JSON responses are wrapped in another JSON object, Milogo support filtering the actual payload (see example wrapped):

// GET /products?fields=code,price(amount)
{
  "data": [
    {
      "code": 1,
      "price": {
        "amount": 100
      }
    },
    ...
  ],
  "_metadata": {
    ...
  }
}

Getting Started

As any gin middleware, Milogo is really easy to use and setup, you can follow the README in the github repository, but basically:

r := gin.Default()
r.Use(Milogo())

is enough to add Milogo middleware to your api.

In the previous example Milogo is applied to every single endpoint, but it is also possible to apply only to a group of endpoints, or just to an specific endpoint, e.g.

group := r.Group("/products", milogo.Milogo())
group.GET("", productsHandler)

In the previous example, only the /products group would have the Milogo’s middleware applied.

Conclusion

Milogo is designed to simplify REST API development and improve client-server interactions. Check out the GitHub repository for examples and documentation.

Feel free to reach out or contribute — let’s make REST APIs efficient together!