gRPC is an RPC framework developed by Google. It uses HTTP/2 for transport and Protobuf for serialization, making it faster and more structured than traditional REST/HTTP+JSON – but less readable, so it is mainly used for internal microservice communication.

Explanation

Traditional HTTP (REST + JSON)

Client → POST /users HTTP/1.1
         Content-Type: application/json
         {"name": "Alice", "age": 30}

Server → 200 OK
         {"id": 1, "name": "Alice"}

• Operations are defined by URL + HTTP method
• Data format is JSON (human-readable text)
• Based on HTTP/1.1 (each request uses an independent connection)

How gRPC does it

Client → calls UserService.CreateUser(CreateUserRequest)
Server → returns CreateUserResponse

• Services and messages are defined in .proto files; calling them feels like calling a local function
• Data format is Protobuf (binary, not directly readable)
• Based on HTTP/2 (multiplexing – a single connection handles multiple requests)

Core differences

Knowledge Sugar

What is HTTP/2 multiplexing?

In HTTP/1.1, each request must wait for the previous response before sending the next one (or open a new connection). HTTP/2 can handle multiple request/response pairs in parallel over a single connection, significantly reducing latency.

Streaming

gRPC supports four communication modes, which are hard to do with REST:

Unary:              one request → one response (most common)
Server streaming:   one request → multiple responses (e.g. real-time push)
Client streaming:   multiple requests → one response (e.g. uploading chunked data)
Bidirectional:      multiple requests ↔ multiple responses (e.g. real-time chat)

Relation to Protobuf gRPC’s data format is Protobuf – see the earlier post on Protobuf Reserved Fields & API Versioning for more context.

Language preference does not need to be a request parameter. HTTP already has the Accept-Language header for this – the server reads it directly from the header, and the client does not need to pass an extra field.

Explanation

What is Accept-Language?

It is a request header defined by the HTTP standard (RFC 7231) that tells the server which languages the client prefers. Browsers set it automatically based on the user’s system language. API clients can set it manually:

Accept-Language: zh-TW,zh;q=0.9,en;q=0.8

• Multiple languages are separated by commas
• q is the quality factor, ranging from 0 to 1 (default 1.0) – higher means more preferred
• The example above: prefer zh-TW, then zh, then en

How does the server read it?

In Go, just get it from the header and parse:

1lang := r.Header.Get("Accept-Language")
2// "zh-TW,zh;q=0.9,en;q=0.8"
3
4// Simple approach: take the first one (highest priority)
5preferred := strings.Split(lang, ",")[0]  // "zh-TW"

In practice you would use an existing library to parse the full q-value ordering, match against the server’s supported languages, and fall back to a default if nothing matches.

Why is this better than a request parameter?

Knowledge Sugar

Content Negotiation

Accept-Language is part of HTTP content negotiation – the client tells the server “here’s what I can accept” and the server picks the best match from what it can provide. Related headers in the same family:

• Accept: preferred response format (application/json, text/html)
• Accept-Encoding: preferred compression (gzip, br)

Usually handled in middleware

No need for every handler to read the header itself. Parse it in middleware, put the result in the context, and let downstream handlers read from there:

1func LanguageMiddleware(next http.Handler) http.Handler {
2    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
3        lang := parseAcceptLanguage(r.Header.Get("Accept-Language"))
4        ctx := context.WithValue(r.Context(), "lang", lang)
5        next.ServeHTTP(w, r.WithContext(ctx))
6    })
7}

API request validation should happen on both sides, but with different roles: the client provides instant UX feedback, while the server enforces all business logic validation. The server side is mandatory because client validation can be bypassed.

Explanation

Why can’t you skip server-side validation?

Anyone can skip the frontend and hit the API directly. Client-side validation is just a UX optimization; the server is the real enforcement layer.

Cross-field Validation

When fields have logical dependencies (e.g. discount cannot be 0 when eligibility is true), handle it in a Validate() method on the server side:

 1type CreateDiscountRequest struct {
 2    Eligibility bool    `json:"eligibility"`
 3    Discount    float64 `json:"discount"`
 4}
 5
 6func (r CreateDiscountRequest) Validate() error {
 7    if r.Eligibility && r.Discount == 0 {
 8        return errors.New("discount cannot be 0 when eligibility is true")
 9    }
10    return nil
11}

Call it in the handler right after decoding:

1var req CreateDiscountRequest
2json.NewDecoder(r.Body).Decode(&req)
3
4if err := req.Validate(); err != nil {
5    http.Error(w, err.Error(), http.StatusBadRequest) // 400
6    return
7}

Knowledge Sugar

Should you use a validation library?

For simple cases, a hand-written Validate() is enough. When rules get complex or you have many structs, consider go-playground/validator, which supports struct tags for basic rules:

1type Request struct {
2    Name  string  `validate:"required"`
3    Email string  `validate:"required,email"`
4    Age   int     `validate:"gte=0,lte=130"`
5}

But cross-field logic (dependencies between fields) still needs a custom validator – no library handles your business logic for you.

Return 400 or 422?

• 400 Bad Request: malformed input, parse failure
• 422 Unprocessable Entity: valid format but failed business logic validation (like the cross-field error above)

Semantically 422 is more precise, but in practice many APIs use 400 for everything. Follow your team’s convention.

BFF (Backend For Frontend) is an architecture pattern where you build a dedicated backend layer for each frontend client, instead of having all clients share a single API.

Explanation

Why do you need BFF?

Different clients have very different data needs. Take an e-commerce platform as an example:

• Mobile app: small screen, limited bandwidth, needs only a few compact fields
• Web browser: can show richer data, needs more fields
• Third-party partners: yet another set of data format requirements

With a single shared API, two problems arise:

• Over-fetching: returning fields the client does not use
• Under-fetching: one request is not enough, so the client sends multiple requests

BFF adds a layer between clients and backend microservices:

Mobile App  →  Mobile BFF  ┐
Web App     →  Web BFF     ├─→  microservices
Partner API →  Partner BFF ┘

Each BFF handles:

1. Aggregating responses from multiple microservices (one request instead of many)
2. Trimming data to the format that specific client needs
3. Client-specific logic (e.g. mobile pagination)

Who maintains the BFF?

Usually the frontend team, so they can adjust the API format on their own without waiting for backend changes.

Knowledge Sugar

BFF vs API Gateway

These are easy to confuse, but they serve different purposes:

In practice they can coexist – the API Gateway sits in front handling common concerns, while BFFs sit behind it doing client-specific data aggregation.

When do you not need BFF?

• Only one client type (e.g. web only)
• The backend is a monolith with nothing to aggregate
• The team is small and maintaining multiple BFFs costs more than it saves

When removing a response field from a protobuf message, you cannot simply delete it – you must mark it as reserved. Otherwise, if a future field reuses the same field number, old clients will misinterpret the new field’s value as the old field.

Explanation

Why is reserved needed?

Protobuf identifies data on the wire by field number, not field name. So when you:

1. Originally have string old_field = 3; in a response message
2. Integrate a new external service, the backend logic changes, this field is no longer populated, so you delete it
3. Later add int32 new_field = 3; (reusing number 3)

At this point, clients still using the old proto definition will receive the response and try to read new_field’s value as old_field – the type mismatch causes a crash.

Correct approach: mark it as reserved

1message MyResponse {
2  reserved 3, 5;                    // reserve these field numbers from reuse
3  reserved "old_field", "another";  // also reserve the field names (prevents accidental reuse in code)
4
5  string active_field = 1;
6  int32 other_field = 2;
7}

With reserved in place, any attempt to reuse those numbers or names will cause a protoc compilation error.

What is the relationship between v2alpha and v2beta?

These are API version stability labels, following Google AIP (API Improvement Proposals) naming conventions, commonly seen in gRPC / proto package naming:

The typical progression is: v2alpha1 -> v2alpha2 -> v2beta1 -> v2beta2 -> v2

How it looks in proto files:

1// Experimental version
2package mycompany.myservice.v2alpha1;
3
4// Feature-complete but still being polished
5package mycompany.myservice.v2beta1;
6
7// Stable release
8package mycompany.myservice.v2;

Different versioned packages are completely independent namespaces that can coexist, allowing old and new clients to each use their corresponding version.

Knowledge Sugar

Two ways to write reserved, and they can be separate or combined:

1reserved 1 to 3;       // contiguous range
2reserved 1, 2, 3;      // individual listing
3reserved "foo", "bar"; // reserve names (recommended to do both, prevents typo reuse)

Difference from deprecated:

• deprecated = true is a human-readable warning telling developers “this field is not recommended anymore,” but it still works
• reserved is enforced at compile time – it completely blocks any reuse

Practical mindset when designing new proto contracts:

• A field number, once released, is forever – before deleting a field, decide whether it needs reserved
• Alpha/Beta versions give you room to experiment; once you reach a stable v2, removing or changing fields requires a formal deprecation process

Further reading:

• Google AIP-180: definition of breaking vs non-breaking changes
• oneof field numbers in protobuf also need reserved
• Buf (buf.build): a protobuf linter that can automatically detect breaking changes