Irina Scurtu | Blog

Eventual Consistency Explained

2026-08-20T00:00:00Z

Not a bug. A trade-off you need to understand.

Update your profile picture, refresh the page on your phone, and for a second the old one is still there. Is that a bug? Most people's instinct is yes: I just saved this, why doesn't everything show it immediately?

It isn't a bug. It's eventual consistency, and if you build distributed systems, you're relying on it constantly, whether you've designed for it or not.

The Promise We Want, and What It Costs 🔗

The promise everyone wants is simple: you update something, and every service, every region, every cache sees it instantly. One version of the truth, always. That's strong consistency, and it's a completely reasonable thing to want.

It's also expensive. Guaranteeing that every node agrees before you consider a write done means coordination. And coordination across a network, especially across regions, means waiting on round trips you don't control. Do that on every write, at scale, and your system's latency is now bounded by your slowest node and your worst network hop.

So most distributed systems don't do that. They accept a weaker guarantee in exchange for speed and availability, and call it eventual consistency.

What Eventual Consistency Actually Means 🔗

Here's the mechanism: a write lands on one node (or a small subset of nodes). The other nodes find out later, through replication, gossip, or some other propagation mechanism, not as part of the original write. If no new updates come in, every node eventually converges on the same value.

That word "eventually" is doing a lot of work, and it's worth being precise about it. It's a promise about outcome, not about timing. Given enough time and no further writes, all replicas agree. In practice, "eventually" is usually milliseconds, sometimes seconds, and only occasionally something you'd notice. But the guarantee itself says nothing about how fast. It only says eventually, which is a liveness guarantee, not a timing one.

sequenceDiagram
    participant Client
    participant A as Node A
    participant B as Node B
    participant C as Node C

    Client->>A: Write(value = X)
    A-->>Client: Ack (write accepted)
    Note over A,C: Client already sees success.<br/>Replication starts now, not before.
    A->>B: Replicate X
    A->>C: Replicate X
    Note over B: Still serving the old value<br/>until replication lands
    B-->>B: Converges on X
    C-->>C: Converges on X

The CAP Trade-Off 🔗

This is where the CAP theorem shows up. It's less abstract than it sounds once you connect it to a decision you're already making. CAP says a distributed system can only guarantee two of these three properties at once, and in practice, partition tolerance isn't optional for any system that spans more than one node:

graph LR
    C((Consistency))
    A((Availability))
    P((Partition<br/>Tolerance))

    C ---|"CA: no partition tolerance"| A
    C ---|"CP: consistent, may be unavailable"| P
    A ---|"AP: available, eventually consistent"| P

That leaves a real choice only once a partition actually happens: stay consistent, where every node sees the same data, or stay available, where every request gets a response, even if it's not the latest data. You can't fully have both during that partition.

Eric Brewer, who proposed CAP back in 2000, revised his own framing in 2012 for exactly this reason. Partition tolerance was never really a dial you could turn off for a system with more than one node, so treating it as an equal third option was misleading. The only decision that matters is what happens to consistency and availability once a partition actually hits.

Real systems announce which side of that decision they land on. CP (consistency + partition tolerance) systems, like MongoDB in its default configuration or HBase, choose consistency: rather than serve you something wrong, they'd rather reject the request. AP (availability + partition tolerance) systems, like Cassandra or DynamoDB, choose availability: they'll serve you data that might be a few writes behind rather than nothing at all, and lean on eventual consistency to close the gap afterward. CA (consistency + availability) systems, like a traditional PostgreSQL or MySQL install running in one place, get to keep both, but only because they were never asked to survive a partition between nodes. Spread that same database across two data centers, and CA quietly stops being on the table.

Eventual consistency is the deliberate choice of availability over strong consistency. You're saying: I'd rather my system keep responding, even with slightly stale data somewhere, than refuse to answer. It shouldn't have to wait until everyone agrees. For a lot of systems, that's exactly the right call. It's worth naming it as a call, not something that just happens to you.

Where You're Already Using It 🔗

This isn't exotic. You might assume eventual consistency is something only distributed-systems specialists deal with. Consider how much of your daily infrastructure already works this way.

DNS is the oldest example: update a record and it can take minutes to propagate everywhere, not milliseconds. CDNs cache content at edge nodes and take time to invalidate it after a change. Social media feeds (likes, comments, view counts) propagate asynchronously. Nobody expects a like count to update everywhere in the same instant. And if you run a primary/replica database setup, your read replicas are, by construction, eventually consistent with the primary. There's always some lag, even if it's usually small enough that nobody notices.

You've been relying on eventual consistency for years. The only question is whether you've been designing for it on purpose.

What This Means in Practice 🔗

Designing for eventual consistency on purpose looks different from tolerating it by accident. A few things that help:

Show what the user submitted, not what's confirmed. This is optimistic UI. Update the screen right after the action. Don't wait on a round trip to every replica before showing the change.
Retries should be idempotent. If an operation might have partially succeeded, retrying it again needs to be safe, not additive.
Version your data. ETags, sequence numbers, or vector clocks let you detect conflicts instead of silently losing one write to another.
Conflicts need to be resolvable, not just detectable. "Last write wins" is the easy default, but it isn't always the right one. Know when it's acceptable and when it isn't.

None of this has to be all-or-nothing at the system level, either. Most distributed databases let you dial consistency per operation instead of per deployment. Cassandra lets you ask for a QUORUM read on an account balance and an ONE read on an activity feed, in the same application. DynamoDB defaults to eventually consistent reads but gives you a strongly consistent read on request, at roughly double the read cost. MongoDB's writeConcern and readPreference settings do the same job. Pick the guarantee per query, not per database.

Know the specific failure patterns to watch for too. They're the same handful every time:

Reading your own write and getting the stale value back (you just saved this, why doesn't it show?).
Stale aggregates, where a count or total lags behind the records it's summarizing.
Two users updating the same record concurrently, with one silently overwriting the other.
Downstream actions (an email, a notification) firing off the back of data that's already out of date by the time they run.

None of these are exotic bugs. They're the predictable consequences of eventual consistency meeting code that was written as if it were strongly consistent.

Not every part of your system should take the eventually-consistent trade, either. Financial transactions (debits and credits) need to be atomic. Inventory reservation needs strong consistency, or two customers can both "successfully" claim the last item in stock. A revoked authentication token needs to be invalid immediately, not eventually. Eventual consistency is a sensible default for a lot of your system. It isn't a universal rule. Treat it as one, and you'll end up debugging a double-sold item at 2am.

Closing 🔗

Eventual consistency trades "always correct" for "always available." For most of what you build, that's the right trade. The mistake isn't choosing it. The mistake is not knowing you've chosen it.

The worst eventual consistency bugs I've seen didn't come from the trade-off itself. They came from nobody realizing they'd made a trade-off, until a user noticed their own change had disappeared.

PS: Let me know if I missed anything, ping me on Twitter/X or LinkedIn, and follow along there if you'd like more of this. Let's chat.

REST APIs in Production: Pagination, HATEOAS, and the Patterns That Actually Matter (Part 3 of 3)

2026-08-13T00:00:00Z

This is the last post in a three-part series on REST API design. The first post covered REST's constraints and HTTP semantics. The second covered resource design, versioning, and authentication. This one covers what separates a demo API from a production one.

Pagination 🔗

Always paginate collections that can grow without bound. Returning 50,000 records in one response is a denial-of-service problem waiting to happen.

Offset-Based Pagination 🔗

GET /orders?offset=0&limit=20
GET /orders?offset=20&limit=20
GET /orders?page=2&per_page=20

Simple to implement and query. Allows jumping to arbitrary pages.

Weakness: inconsistent results under concurrent writes. A record inserted between page 1 and page 2 requests can show up as a duplicate. If one is deleted, you may skip a record. Performance also degrades at high offsets in most databases.

Cursor-Based Pagination 🔗

GET /orders?limit=20
# Returns: { "data": [...], "cursor": "eyJpZCI6MjB9" }

GET /orders?after=eyJpZCI6MjB9&limit=20

The cursor encodes a position in the result set. It's typically the ID or sort key of the last item returned. Each page request is a stable query from a known position.

Strengths: consistent under concurrent writes, efficient at any depth, suits real-time feeds.

Weaknesses: cannot jump to arbitrary pages (only forward/backward), and clients must treat the cursor as opaque.

Keyset Pagination 🔗

A variant of cursor pagination that expresses the position as an explicit field value:

GET /orders?after_id=789&limit=20

Less opaque than encoded cursors, but ties pagination semantics to visible fields.

Response Envelope for Pagination 🔗

Always include pagination metadata:

{
  "data": [ ... ],
  "pagination": {
    "total": 1540,
    "limit": 20,
    "offset": 40,
    "has_next": true,
    "has_previous": true
  },
  "links": {
    "self":  "/orders?offset=40&limit=20",
    "next":  "/orders?offset=60&limit=20",
    "prev":  "/orders?offset=20&limit=20",
    "first": "/orders?offset=0&limit=20",
    "last":  "/orders?offset=1520&limit=20"
  }
}

The links object connects this to HATEOAS, more on that next.

HATEOAS 🔗

HATEOAS (Hypermedia as the Engine of Application State) is REST's most misunderstood, most often omitted constraint. According to Fielding himself, it's also the part that makes an API truly RESTful.

The idea: a client moves through an API using links in responses. It needs little upfront knowledge of URI structure. A human clicks through a website by following links. A REST client should do the same instead of hardcoding URI structure it was never given.

What It Looks Like 🔗

GET /orders/789

{
  "id": "789",
  "status": "pending",
  "total": 142.50,
  "customer": {
    "id": "42",
    "name": "Alice"
  },
  "_links": {
    "self":     { "href": "/orders/789" },
    "cancel":   { "href": "/orders/789/cancel", "method": "POST" },
    "customer": { "href": "/users/42" },
    "payment":  { "href": "/payments?orderId=789" }
  }
}

The server controls what actions are available. If the order is already cancelled, the cancel link disappears. The client doesn't need to know the cancellation rules. It just checks whether the link is present.

Media Types and HATEOAS 🔗

The _links pattern above is informal. There are standardized hypermedia formats:

HAL (Hypertext Application Language): uses _links and _embedded, widely adopted
JSON:API: a more opinionated full specification for request/response format
Siren: includes actions with typed fields, more expressive for write operations
Collection+JSON: designed specifically for collection resources

The Reality of HATEOAS Adoption 🔗

HATEOAS is theoretically correct and has genuine benefits for client decoupling. In practice, most production APIs don't implement it. Most clients don't use it even when offered. The reasons are pragmatic. Statically typed clients often prefer a well-documented contract over dynamic link discovery. Tooling for hypermedia clients also isn't as mature as tooling for OpenAPI-described APIs.

Know this so you decide deliberately, not by default. For public APIs with diverse clients and long lifespans, HATEOAS is worth the investment. For internal APIs between services you control, a well-maintained OpenAPI spec may be more practical.

Filtering, Sorting, and Searching 🔗

Filtering 🔗

Use query parameters to filter collections:

GET /orders?status=pending
GET /orders?status=pending&customerId=42
GET /products?minPrice=10&maxPrice=100&category=electronics

For complex filters, some APIs use a structured query language:

GET /products?filter=price:lt:100,category:eq:electronics

Or a JSON-encoded filter (though this can be awkward in URLs):

GET /products?filter={"price":{"lt":100},"category":"electronics"}

Be consistent and document your filter syntax explicitly.

Sorting 🔗

GET /orders?sort=createdAt
GET /orders?sort=createdAt:desc
GET /orders?sort=-createdAt          # minus prefix for descending
GET /orders?sort=status,createdAt:desc

Always document the default sort order, and make it stable. Include a unique field as a tiebreaker.

Searching 🔗

Full-text search usually warrants a dedicated endpoint or query parameter:

GET /products?q=wireless+headphones
GET /search?q=wireless+headphones&type=products

For sophisticated search requirements, dedicated search endpoints with POST bodies can be appropriate:

POST /products/search

{
  "query": "wireless headphones",
  "filters": { "inStock": true, "priceMax": 200 },
  "sort": { "field": "relevance", "order": "desc" },
  "pagination": { "limit": 20, "offset": 0 }
}

POST works for search when the query is too complex for a URL. It's pragmatic, but it sacrifices cacheability.

Sparse Fieldsets and Field Selection 🔗

Large resources with many fields are expensive to transfer. They often contain fields a given client doesn't need. Field selection lets clients request only what they need:

GET /users/42?fields=id,name,email
GET /orders?fields=id,status,total&include=customer.name

This is particularly important for mobile clients on limited bandwidth.

Content Negotiation 🔗

REST embraces HTTP's content negotiation mechanism. Clients can request specific response formats:

# Request JSON
curl -H "Accept: application/json" https://api.example.com/users/42

# Request XML
curl -H "Accept: application/xml" https://api.example.com/users/42

The server indicates what it returned:

Content-Type: application/json; charset=utf-8

If the server cannot produce the requested format, it returns 406 Not Acceptable.

For versioning via content type:

curl -H "Accept: application/vnd.myapi.v2+json" https://api.example.com/users/42

Rate Limiting 🔗

Every public API needs rate limiting. Return standard headers so clients can manage their behavior:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 742
X-RateLimit-Reset: 1735689600
Retry-After: 3600

When a client exceeds the limit, return 429 Too Many Requests with a Retry-After header.

Common rate limiting strategies:

Fixed window: count requests in a fixed time window (simple, but allows burst at window boundary)
Sliding window: rolling time window (smoother, more expensive)
Token bucket: tokens replenish at a fixed rate, bursts allowed up to bucket size
Leaky bucket: requests processed at a fixed rate, excess queued or dropped

Provide different rate limit tiers for different clients (authenticated vs. anonymous, free vs. paid).

Idempotency Keys 🔗

For non-idempotent operations like POST, idempotency keys let clients retry safely. There's no risk of duplicate side effects:

curl -X POST https://api.example.com/payments \
  -H "Idempotency-Key: 7f3a2b1c-4d5e-6f7g-8h9i-0j1k2l3m4n5o" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "USD"}'

The server caches the response for the idempotency key for a defined window. A retry with the same key returns the cached response without reprocessing the payment.

This pattern is essential for payment APIs and order creation. It matters for any operation with financial or irreversible consequences.

Conditional Requests and Optimistic Concurrency 🔗

HTTP provides mechanisms for conditional operations via ETags and timestamps.

ETags are version identifiers for a resource:

GET /orders/789

HTTP/1.1 200 OK
ETag: "abc123"

A client can make conditional requests using If-Match to prevent lost updates:

# Only update if the resource still has this ETag (optimistic locking)
curl -X PUT https://api.example.com/orders/789 \
  -H "If-Match: \"abc123\"" \
  -d '{ "status": "processing" }'

Someone else may have modified the resource since the client retrieved it. If so, the server returns 412 Precondition Failed.

For cache revalidation, clients use If-None-Match:

# Only send the body if the resource has changed
curl -H "If-None-Match: \"abc123\"" https://api.example.com/orders/789
# Returns 304 Not Modified if unchanged

If-Modified-Since / Last-Modified work similarly but with timestamps.

Long-Running Operations 🔗

Some operations take seconds or minutes. Don't block. Return 202 Accepted and provide a way to track progress:

POST /reports/generate

HTTP/1.1 202 Accepted
Location: /jobs/report-abc123

{
  "jobId": "report-abc123",
  "status": "pending",
  "statusUrl": "/jobs/report-abc123"
}

GET /jobs/report-abc123

{
  "jobId": "report-abc123",
  "status": "running",
  "progress": 42,
  "startedAt": "2026-03-27T09:00:00Z"
}

GET /jobs/report-abc123

{
  "jobId": "report-abc123",
  "status": "completed",
  "result": { "url": "/reports/2026-q1.pdf" }
}

Alternatively, use webhooks to push completion notifications rather than requiring polling.

API Design Best Practices 🔗

Be Consistent 🔗

Inconsistency is the number one user-experience failure in APIs. Pick conventions for naming, casing, error format, date format, pagination, and versioning, then apply them everywhere.

Field names: camelCase or snake_case, pick one
Dates: ISO 8601 (2026-03-27T09:00:00Z) always, never Unix timestamps in mixed APIs
Booleans: isActive, not active, enabled, or status: "true"

Document Everything 🔗

An API without documentation is incomplete. Use OpenAPI 3.x to describe your API. It enables generated documentation, client SDK generation, request validation, and contract testing.

Document:

Every endpoint, method, and path parameter
Every request body field (required vs. optional, constraints)
Every response status code and body
Authentication requirements
Rate limits
Deprecation timelines

Use HTTPS Exclusively 🔗

Never offer plain HTTP. Redirect all HTTP traffic to HTTPS. Use HSTS (Strict-Transport-Security) to prevent downgrade attacks.

Design for Your Consumer 🔗

APIs are products. Talk to the developers who will use your API. Understand their workflows. APIs that are technically correct but operationally awkward get abandoned. I always advise treating your API contract like a public function signature in a library.

Backward Compatibility is a Promise 🔗

Once you publish an endpoint, clients depend on it. Make breaking changes rare, communicate them well, and support them with a migration path and a generous deprecation window.

Keep Actions Atomic 🔗

An endpoint should either succeed completely or fail completely. Partial success is a consistency nightmare. If a batch operation partially fails, return a clear, structured response. It should identify which items succeeded and which failed, with specific error details.

Don't Return 200 with an Error Body 🔗

This bears repeating. Use the HTTP status code correctly. Your monitoring, your clients, and your own sanity will thank you.

Closing 🔗

Most "REST APIs" in production implement a subset of the constraints. They ignore the rest, particularly HATEOAS. That's a pragmatic reality of software engineering. It's fine, as long as it's a deliberate choice.

Think about it. The difference between a good API and a frustrating one usually isn't the technology. It's the care taken with every small decision. The status code, the error message, the version strategy, the pagination contract. Those decisions compound. Clients you don't know yet will inherit them.

Build APIs you'd want to consume yourself.

PS: Let me know if I missed anything. Ping me on Twitter/X or LinkedIn, and follow along there if you'd like more of this. Let's chat.

REST API Design: Resources, Versioning, and Auth That Hold Up (Part 2 of 3)

2026-08-06T00:00:00Z

In the first post in this series, I covered REST's architectural constraints and the HTTP semantics (methods, status codes) that most APIs get subtly wrong. Constraints and semantics get you a technically correct API. They don't get you a good one.

A good API needs resources named sensibly and a versioning strategy that won't break your clients every quarter. It also needs an authentication pattern matching your threat model, and errors that tell the caller something useful. That's what this post covers.

REST API Resource Design 🔗

Resources are the nouns of your API. Good resource design is the single biggest factor in how usable and evolvable your API will be.

URIs Should Identify Resources, Not Actions 🔗

# Good - noun-based, resource-centric
GET  /orders
GET  /orders/789
POST /orders
PUT  /orders/789
DELETE /orders/789

# Bad - verb-based, RPC-style
POST /getOrder
POST /createOrder
POST /deleteOrder

The HTTP method carries the action. The URI carries the identity of the resource the action applies to.

Singular vs. Plural 🔗

Use plurals for collections consistently:

/users          # collection
/users/42       # single resource
/users/42/posts # sub-collection

Mixing singular and plural is a maintenance and documentation headache.

Hierarchical Relationships 🔗

Nest resources to express ownership or containment, but limit nesting depth:

/users/42/orders         # orders belonging to user 42
/users/42/orders/789     # order 789 belonging to user 42

Deep nesting (more than two levels) is a sign that you may need to reconsider your resource model. /users/42/orders/789/items/1/reviews/5 is hard to work with. In my opinion, it's better to use query parameters to filter at the top-level collection:

GET /orders?userId=42

Resource Identifiers 🔗

Prefer opaque, stable identifiers. UUIDs or ULIDs are better than auto-increment integers for several reasons:

They don't expose record counts (a security and competitive concern)
They can be generated client-side without a round-trip
They're safe to use across environments without collision

Once you publish a URI, it is a contract. Change it only with proper versioning and redirect support.

Controller Resources 🔗

Some operations don't map cleanly onto CRUD. Use controller resources for these, named with a verb and invoked with POST:

POST /orders/789/cancel
POST /accounts/42/verify-email
POST /payments/refund

This is better than bending PUT or PATCH into something unnatural.

Versioning Strategies 🔗

APIs change. Resources get new fields, old fields get removed, behavior changes. Versioning is how you manage change without breaking existing clients.

URI Versioning 🔗

/v1/users
/v2/users

Pros: explicit, easy to route at the infrastructure level, easy to document and test separately, shows up clearly in logs.

Cons: technically violates REST's uniform interface (the same resource should have one canonical URI), pollutes the URI space, encourages "big bang" version increments rather than incremental evolution.

This is the most pragmatic approach and the most widely used.

Header Versioning 🔗

GET /users
Accept: application/vnd.myapi.v2+json

Pros: URIs remain stable, aligns with HTTP content negotiation, cleaner theoretically.

Cons: harder to test in a browser, not visible in logs without extra work, requires clients to set headers correctly, harder to cache with some intermediaries.

Query Parameter Versioning 🔗

GET /users?version=2

Pros: easy to test, explicit, no header management.

Cons: version in the query string is semantically awkward (it's not a filter parameter), can interfere with caching.

Additive Changes vs. Breaking Changes 🔗

The best versioning strategy is to not break clients in the first place. Additive changes are generally safe:

Adding new fields to a response
Adding new optional request parameters
Adding new endpoints
Adding new values to an enum (this can break strict deserializers, so communicate it)

Breaking changes require a new version:

Removing or renaming fields
Changing field types
Changing URI structure
Changing status codes for existing operations
Removing endpoints

Be pragmatic about it, and don't take it to the extreme. An API version number is not a build number. Don't do that.

Versioning in Practice 🔗

# Requesting a specific version via header
curl -H "Accept: application/vnd.myapi.v2+json" https://api.example.com/users

# URI versioning
curl https://api.example.com/v2/users

Maintain multiple versions simultaneously during a deprecation window. Communicate deprecation timelines clearly via Deprecation and Sunset response headers:

Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

Authentication Patterns 🔗

REST is stateless, which means credentials travel with every request. There are several established patterns.

API Keys 🔗

The simplest approach. You issue a key to a client, who sends it with every request, typically in a header:

curl -H "X-API-Key: abc123xyz" https://api.example.com/data

Or as a Bearer token variant:

curl -H "Authorization: ApiKey abc123xyz" https://api.example.com/data

Pros: simple to implement and use, easy to rotate. Cons: no expiration built in, broad access (all-or-nothing unless scoped), key must be kept secret.

HTTP Basic Authentication 🔗

Username and password encoded as Base64 in the Authorization header:

curl -u username:password https://api.example.com/data
# Which sends:
# Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Never use Basic auth over plain HTTP. Base64 only obscures credentials; it doesn't encrypt them. Only acceptable over HTTPS.

Bearer Tokens (JWT / OAuth 2.0) 🔗

The dominant pattern for modern APIs. You obtain a token through an authentication flow and include it as a Bearer token:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." https://api.example.com/data

JWTs (JSON Web Tokens) are self-contained: they encode claims (user ID, roles, expiry) and are cryptographically signed. The server can validate them without a database lookup.

Key properties to verify when processing JWTs:

Signature validity (using the correct public key or shared secret)
exp claim (not expired)
iss claim (issued by the expected authority)
aud claim (intended for your service)

OAuth 2.0 defines flows for obtaining tokens. The authorization code flow is appropriate for delegated access on behalf of a user. Client credentials flow is appropriate for machine-to-machine APIs.

Mutual TLS (mTLS) 🔗

Both client and server present certificates. Strong authentication with no bearer token to steal, but operationally complex (certificate management, rotation). Common in zero-trust internal service meshes.

Choosing a Pattern 🔗

Public API, external developers: OAuth 2.0 with API keys for non-delegated access
Service-to-service: mTLS or client credentials flow
Internal tooling: API keys or JWT with short expiry
User-facing mobile/web: OAuth 2.0 authorization code flow with PKCE

Error Handling 🔗

Error responses deserve as much design attention as success responses. A client that receives an error needs to know what went wrong and why. It also needs to know what, if anything, it can do about it.

Structure Your Error Responses 🔗

Ad-hoc error messages are hard to handle programmatically. Define a consistent error structure and use it everywhere:

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request payload contains invalid values.",
  "instance": "/orders/create",
  "errors": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "Email address is not in a valid format."
    },
    {
      "field": "quantity",
      "code": "OUT_OF_RANGE",
      "message": "Quantity must be between 1 and 100."
    }
  ]
}

This follows RFC 7807 (Problem Details for HTTP APIs), a standard worth adopting. The type field is a URI that identifies the error type (it should resolve to documentation). The instance field identifies the specific occurrence.

Be Specific 🔗

A 400 with "bad request" is nearly useless. Tell the client:

Which field(s) failed validation
What constraint was violated
What the expected format or range is

Don't Leak Internals 🔗

Error responses must never expose:

Stack traces
Database error messages
Internal server paths
Framework-level exceptions
Secrets or keys

Log those internally. Return only what the client needs to understand and act on the error.

Distinguish Permanent from Transient Errors 🔗

4xx errors are the client's fault. Retrying the same request unchanged is pointless.
5xx errors are the server's fault. The client may retry, ideally with exponential backoff and jitter.

Make this distinction explicit in your API documentation and, where possible, in the response itself.

Correlation IDs 🔗

Return a correlation ID in every error response (and ideally every response):

X-Correlation-Id: 7f3a2b1c-4d5e-6f7g-8h9i-0j1k2l3m4n5o

This allows support teams to trace a client-reported error back to server-side logs without guessing.

Closing 🔗

Resource design, versioning, and auth get your API to a place where it's usable and safe to evolve. What's still missing is what happens once real traffic hits it: pagination, discoverability, rate limits, and idempotency.

That's what the last post in this series covers.

PS: Let me know if I missed anything. Ping me on Twitter/X or LinkedIn, and follow along there if you'd like more of this. Let's chat.

REST API Design: The Constraints and HTTP Semantics Everyone Skips (Part 1 of 3)

2026-07-30T00:00:00Z

REST is everywhere. Almost every web application, mobile app, and microservice you interact with today exposes or consumes a REST API. Yet most developers learn REST by cargo-culting patterns they see in tutorials. They slap HTTP verbs on endpoints and call it done.

This is the first post in a series on REST API design that goes deeper than the tutorials. We'll start with the part everyone skips: what REST actually is, the constraints Roy Fielding defined it by, and the HTTP semantics that most APIs get subtly wrong. That means methods and status codes.

What REST Actually Is 🔗

REST stands for Representational State Transfer. Roy Fielding defined it in his 2000 doctoral dissertation, where he described the architectural style that underpins the web itself.

The key insight in Fielding's thesis is that REST is not a protocol or a standard. It is an architectural style: a set of constraints that, applied together, produce desirable properties in a distributed hypermedia system. If your API doesn't satisfy those constraints, it isn't REST. It may still be a perfectly useful HTTP API, but calling it REST is technically incorrect.

This distinction matters more than it might seem. Fielding designed REST to be highly scalable, loosely coupled, and evolvable over time. Those properties emerge from the constraints, not from any single choice like "use JSON" or "put the ID in the URL". Understanding the constraints is understanding the why behind every REST best practice.

The Six Architectural Constraints 🔗

Fielding defined six constraints. The first five are mandatory; the sixth is optional.

1. Client-Server 🔗

A uniform interface separates the client and server. The client is responsible for the user interface and user experience. The server is responsible for data storage, business logic, and security.

Why it matters: This separation improves portability of the UI across platforms and scalability of the server components. Neither side needs to know the implementation details of the other. A web client, a mobile client, and a CLI tool can all consume the same API. The server doesn't care which one is making the request.

2. Stateless 🔗

Each request from a client to a server must contain all the information necessary to process it. The client keeps all session state. The server stores no client context between requests.

Why it matters: Statelessness enables horizontal scaling. Any server in a pool can handle any request because no server holds session state. It also improves visibility: you can understand a single request in isolation, which helps with debugging and monitoring. And it improves reliability, since partial failures don't leave dangling server-side sessions.

The practical consequence: if a user is authenticated, the authentication token travels with every single request. The server never says "I remember you from last time." It re-validates the token on every call.

3. Cacheable 🔗

Responses must define themselves as cacheable or non-cacheable. If a response is cacheable, the client (or an intermediate proxy) can reuse that response for equivalent future requests.

Why it matters: Caching eliminates some client-server interactions entirely, improving efficiency, scalability, and perceived performance. HTTP already has a rich caching model (Cache-Control, ETag, Last-Modified, Expires), and REST makes full use of it.

Getting caching right requires deliberate thought about:

Which resources change frequently vs. infrequently
Whether two requests are truly equivalent (same query parameters, same Accept header, etc.)
Conditional requests (If-None-Match, If-Modified-Since) for cheap revalidation

4. Uniform Interface 🔗

This is the central constraint that distinguishes REST from other network-based styles. It has four sub-constraints:

Identification of resources. Stable identifiers (URIs) identify each resource. The resource and its representation are distinct. The server might store user data in a relational database. It can represent that data as JSON, XML, or HTML, depending on what the client requests.

Manipulation of resources through representations. When a client holds a representation of a resource, including any metadata, it has enough information to modify or delete the resource. It just needs permission.

Self-descriptive messages. Each message includes enough information to describe how to process it. A Content-Type: application/json header tells the recipient exactly how to interpret the body. This decouples message processing from the application logic.

Hypermedia as the engine of application state (HATEOAS). Clients interact with the application entirely through hypermedia that the server provides dynamically. I cover this one in detail in the last post of this series.

Why it matters: A uniform interface simplifies the architecture and makes it easier to evolve parts of the system independently. The cost is efficiency: the interface generalizes rather than optimizing for any specific use case. That is an explicit and intentional trade-off in REST.

5. Layered System 🔗

The architecture must be composable from hierarchical layers. A client cannot tell whether it's talking directly to the server or to an intermediary. You can insert intermediaries, such as load balancers, API gateways, caches, and security proxies, transparently.

Why it matters: Layers let you enforce security policies at the boundary, cache aggressively at edge nodes, and load-balance without clients knowing. They also let you evolve infrastructure independently from application logic. HTTPS termination at a load balancer is a layered system in action.

6. Code on Demand (Optional) 🔗

Servers can extend client functionality by transferring executable code, like JavaScript running in a browser. This constraint is optional because it reduces visibility. You can't easily audit what code a client will execute, and it creates coupling.

Most API design work ignores code on demand. It shows up primarily in browser-based applications, not in service-to-service APIs.

HTTP Methods 🔗

HTTP provides a small vocabulary of methods (also called verbs). REST maps operations on resources to this vocabulary. Each method carries a defined semantic and a set of properties.

The Core Methods 🔗

Method	Semantics	Safe	Idempotent	Request Body	Response Body
GET	Retrieve a resource or collection	Yes	Yes	No	Yes
POST	Create a subordinate resource, or trigger a process	No	No	Yes	Yes
PUT	Replace a resource entirely	No	Yes	Yes	Yes
PATCH	Partially update a resource	No	No (usually)	Yes	Yes
DELETE	Remove a resource	No	Yes	Optional	Optional
HEAD	Same as GET but body omitted	Yes	Yes	No	No
OPTIONS	Retrieve supported methods and CORS preflight	Yes	Yes	No	Yes

Safe means the method should not have any observable side effects on the server. Clients (and proxies) can prefetch or retry safe methods freely.

Idempotent means that multiple identical requests produce the same server state as a single request. A DELETE /users/42 should have the same effect whether called once or ten times. This property is what makes retries safe.

Common Misuses 🔗

POST for everything. Using POST for reads, updates, and deletes is a common anti-pattern. It throws away idempotency and prevents HTTP-layer caching.

PUT when you mean PATCH. PUT replaces the entire resource. If a client sends a PUT with a partial payload and the server accepts it, the result behaves like PATCH. On paper, though, it's still PUT. This creates subtle bugs when clients omit fields they didn't intend to clear.

DELETE with a body. While technically possible, HTTP clients and intermediaries poorly support bodies on DELETE requests. If you need to delete multiple resources, prefer a separate endpoint or use PATCH on a collection.

POST vs. PUT for creation. Use POST when the server assigns the identifier: you POST to /orders and the server returns /orders/789. Use PUT when the client specifies the identifier: you PUT to /users/alice to create or replace that resource.

HTTP Status Codes 🔗

Status codes are not decoration. They carry semantic meaning and drive client behavior. Using the wrong status code is like raising the wrong exception type. Technically it works, but everyone downstream makes the wrong decisions because of it.

The Five Classes 🔗

1xx, Informational: Rarely used in REST APIs. 100 Continue tells the client it can proceed with a large request body.

2xx, Success: The request was received, understood, and accepted.

3xx, Redirection: Further action needs to be taken to complete the request.

4xx, Client Error: The client sent an invalid request. Retrying the same request unchanged will not succeed.

5xx, Server Error: The server failed to process a valid request. The client may retry.

Key Codes in Detail 🔗

200 OK: General success. The response body contains the result. Appropriate for GET, PUT, PATCH.

201 Created: A new resource was created. The Location header should point to the new resource URI. Appropriate for POST and PUT when creating.

202 Accepted: The server accepted the request for processing, but processing isn't complete. Used for async operations. The response should explain how the client can check status.

204 No Content: Success, but there is nothing to return. Common for DELETE and some PUTs.

301 Moved Permanently: The resource has a new permanent URI. Clients should update their bookmarks.

304 Not Modified: The client's cached copy is still fresh. No body is returned. Used with conditional requests.

400 Bad Request: The server cannot process the request because of a client error (malformed JSON, invalid field values, missing required parameters). Return a body that explains what is wrong.

401 Unauthorized: The request lacks valid authentication credentials. Despite the name, this code means "unauthenticated": the client needs to provide credentials.

403 Forbidden: The client is authenticated but does not have permission to access the resource. Don't return 404 as a security measure unless you want to hide the existence of the resource.

404 Not Found: The resource does not exist. Also used intentionally when a 403 would reveal information you want to protect.

405 Method Not Allowed: The HTTP method is not supported for this resource. The response must include an Allow header listing valid methods.

409 Conflict: The request conflicts with the current state of the resource. Common for optimistic concurrency failures or duplicate creation attempts.

410 Gone: The resource existed but has been permanently deleted. Distinct from 404; useful for caches and clients to know not to ask again.

422 Unprocessable Entity: The request is syntactically valid but semantically wrong (valid JSON, but the business rules reject it). Preferred over 400 for domain validation failures.

429 Too Many Requests: Rate limit exceeded. Include a Retry-After header.

500 Internal Server Error: Generic server failure. Never expose stack traces or internal details.

503 Service Unavailable: The server is temporarily unable to handle requests (overloaded, maintenance). Include Retry-After if known.

The Mistake of Returning 200 for Everything 🔗

A common anti-pattern is returning 200 OK with a body that contains an error flag:

HTTP/1.1 200 OK

{ "success": false, "error": "User not found" }

This forces every client to parse the body to know whether the request succeeded. It breaks HTTP-aware intermediaries (caches will cache failure responses), APM tools, and alerting systems. Use the status code as it was designed to be used.

Closing 🔗

Get the constraints and the HTTP semantics right, and you've built the foundation. Neither one is optional trivia. The rest of REST design only works if two things hold: a client that trusts your status codes, and an architecture that respects statelessness.

Next in this series: how to design the resources themselves, version them without breaking clients, and choose an authentication pattern that matches your actual threat model.

PS: Let me know if I missed anything, ping me on Twitter/X or LinkedIn, and follow along there if you'd like more of this. Let's chat.

Load Shedding: Dropping Requests to Save Your System

2026-07-23T00:00:00Z

Your system under pressure will either shed load deliberately or collapse accidentally.

Traffic spikes. Response times climb. Clients start retrying. The retries add more load. Response times climb further. At some point, the whole thing tips over, and every user gets nothing instead of something.

Most teams I talk to reach for circuit breakers or rate limiters when this happens. Both are good tools. Neither solves this problem. The missing piece, the one that keeps your system alive when everything else is failing, is load shedding.

And the reason most teams don't have it is that they think they already do.

What load shedding actually is (and what it isn't) 🔗

Let me be precise about terms, because this is where most confusion starts.

Rate limiting is about identity and quota. You allow 100 requests per second per client. It doesn't matter how healthy your system is: if a client is over quota, they're rejected. Rate limiting protects you from individual bad actors or runaway clients.

Circuit breakers are about outbound calls. When a downstream service is failing, you stop calling it. The circuit breaker sits between you and your dependencies.

Load shedding is different. It responds to your system's health right now. When CPU is saturating, memory is tight, or your request queue is backing up, you drop requests. It doesn't matter who sent them. Not because of policy. Because you physically cannot serve them well.

The correct HTTP response for a shed request is 503 Service Unavailable with a Retry-After header. Not 429 Too Many Requests: that implies the caller is the problem. 503 says: it's us, not you, try again in a moment.

A minimal implementation in ASP.NET Core 7+ looks like this:

app.Use(async (context, next) =>
{
    var memoryInfo = GC.GetGCMemoryInfo();
    var load = (double)memoryInfo.MemoryLoadBytes / memoryInfo.HighMemoryLoadThresholdBytes;

    if (load > 0.85 || _activeRequests > _maxConcurrent)
    {
        context.Response.StatusCode = 503;
        context.Response.Headers["Retry-After"] = "5";
        return;
    }

    Interlocked.Increment(ref _activeRequests);
    try { await next(context); }
    finally { Interlocked.Decrement(ref _activeRequests); }
});

Simple. But where you put this matters more than you might think.

The cost of where you shed 🔗

Think about it: by the time your middleware runs, your system has already done a lot of work.

The TCP connection was accepted. TLS was negotiated. HTTP/2 frames were parsed. Request headers were read. The ASP.NET Core pipeline started. Middleware before yours executed. Dependency injection resolved your services. Authentication ran.

All of that happened before you decided to return a 503.

Imagine a restaurant that seats guests, hands them menus, and takes their drink order before sending it to the kitchen. Only then does it tell them the kitchen is closed. You've wasted everyone's time, including your own. The earlier you shed, the cheaper each rejection is.

Kestrel exposes MaxConcurrentConnections and MaxConcurrentUpgradedConnections for connection-level limiting, before any HTTP parsing happens. That's the cheapest possible rejection. Your custom middleware is next. Your controller is the most expensive place to shed, because by then you've done almost everything.

builder.WebHost.ConfigureKestrel(options =>
{
    options.Limits.MaxConcurrentConnections = 1000;
});

In practice, you often need both: Kestrel limits as a hard ceiling, middleware for health-signal-based shedding. The point is to push the decision as far left in the stack as you can.

Not all requests deserve equal treatment 🔗

Here's where most load shedding implementations leave a lot on the table.

Standard shedding is binary: you're over threshold, so you reject the next request in the queue. But think about what's in that queue. Health check probes from your orchestrator. Background telemetry events. An analytics batch job. And a user trying to complete a payment.

These are not the same. Dropping a telemetry flush is free. Dropping a payment request has a real cost.

Google's SRE team calls these criticality labels: not all RPCs are equal, so you shouldn't shed them equally. In .NET 7+, you can implement the same idea with endpoint metadata and a priority-aware middleware.

public class SheddingPriorityAttribute : Attribute, IEndpointMetadata
{
    public SheddingPriority Priority { get; }
    public SheddingPriorityAttribute(SheddingPriority priority) => Priority = priority;
}

public enum SheddingPriority { ShedFirst, Normal, Protected }

Then in your middleware, read the priority before deciding whether to shed:

app.Use(async (context, next) =>
{
    if (IsOverloaded())
    {
        var priority = context.GetEndpoint()
            ?.Metadata.GetMetadata<SheddingPriorityAttribute>()
            ?.Priority ?? SheddingPriority.Normal;

        if (priority != SheddingPriority.Protected)
        {
            context.Response.StatusCode = 503;
            context.Response.Headers["Retry-After"] = "5";
            return;
        }
    }

    await next(context);
});

Apply it on your endpoints:

app.MapGet("/metrics", ...).WithMetadata(new SheddingPriorityAttribute(SheddingPriority.ShedFirst));
app.MapPost("/checkout", ...).WithMetadata(new SheddingPriorityAttribute(SheddingPriority.Protected));

Uber described something similar in 2019. They shed roughly 10% of requests during peak events, with no measurable customer impact. The reason? They shed the right 10%.

Static thresholds will betray you 🔗

Most implementations I see use a static threshold: if CPU > 80%, start shedding. In my opinion, this is better than nothing, but it's a guess, and often a late one.

Queueing theory (the M/M/1 model, if you want to look it up) tells us why. Latency doesn't degrade linearly as utilisation climbs. It degrades super-linearly. At 70% utilisation things feel fine. At 85% they start to slip. By 95% you're already in trouble, and that's when the threshold fires.

The smarter signal isn't the absolute CPU value. It's the gradient: is latency getting worse? By how much, and how fast?

Netflix's Concurrency Limits library, which powers parts of their resilience infrastructure, uses TCP Vegas for exactly this. TCP Vegas was designed for network congestion control. Instead of detecting packet loss (the cliff), it detects the onset of congestion by tracking latency increase. Load shedding can work the same way.

There's no standard .NET library that does adaptive shedding like this. It's a genuine gap in the ecosystem. But you can get close with System.Diagnostics.Metrics in .NET 8. Track a rolling P99 latency histogram and engage shedding when the gradient turns positive:

var histogram = meter.CreateHistogram<double>("request.duration.ms");

// Record on every request: histogram.Record(elapsedMs);
// In your shedding middleware: compare rolling P99 against baseline
// When P99 rises >20% over baseline, start shedding

Start shedding when things are getting worse, not when they're already broken. That's the difference between a controlled degradation and a collapse.

What this means in practice 🔗

Load shedding isn't one decision: it's a stack of decisions. Here's how I'd approach it:

Shed at the lowest layer you can: Kestrel limits before middleware, middleware before controllers
Assign criticality to endpoint groups: protect payments, shed telemetry and batch jobs first
Use health signals, not static thresholds: track latency gradient, not just CPU percentage
Return 503 + Retry-After, never 429, for load shedding. The semantics matter
Test it under load by simulating overload in staging and verifying that P99 for accepted requests improves; if it doesn't, your threshold is wrong
Layer it with your other resilience tools. Load shedding doesn't replace rate limiting, circuit breakers, or backpressure; it completes them

Remember: properly implemented load shedding improves the experience for the requests you do accept. By refusing to queue work you can't process quickly, you keep latency tight for everything you take on. AWS and Google both document this. It's counterintuitive until you see the numbers.

Load shedding feels like giving up. It feels like admitting your system can't handle the load, that you're turning users away.

In reality, it's the opposite. It's your system making a deliberate, informed choice about who it can serve well right now. That's better than trying to serve everyone badly and tipping into total failure. Systems that shed deliberately stay alive. Systems that don't shed eventually serve no one.

The question worth asking: has a retry storm ever taken down one of your services? Because load shedding is precisely the thing that would have stopped it.

If you find this useful, ping me on Twitter/X or LinkedIn. A follow there is always appreciated if you'd like more of this. I'm always curious what resilience patterns teams use in production.

When Business Processes Outlive Your Request

2026-04-14T00:00:00Z

A request has a lifecycle measured in milliseconds. A business process has one measured in minutes, hours, or days - and the gap between those two timelines is where most distributed systems go wrong.

The Millisecond and the Multi-Day Process 🔗

Think about what happens when a customer places an order on an e-commerce platform. From the user's perspective, they click "Buy" and wait a few seconds for a confirmation. But behind the scenes, that single click might kick off a workflow that takes days to fully complete: payment authorisation, inventory reservation, warehouse picking, carrier handoff, customs clearance if it's international, and eventually delivery confirmation.

That workflow doesn't live inside a single HTTP request. It can't - not because of any technical limitation on our end, but because the world it's coordinating with operates on a different clock. The payment provider has its own settlement windows. The warehouse runs on shifts. The carrier updates its tracking on its own schedule. And if any of those steps fail mid-flight, the system needs to know what to do, even though the original HTTP connection closed three days ago.

This isn't unique to e-commerce. Loan approval workflows sit in review queues for hours before an underwriter picks them up. User onboarding flows wait for email verification and background checks before granting access. Subscription billing retries over days when a card declines. The moment a business process outlives its triggering request, you have a different class of problem - and request-response thinking is the wrong tool for it.

Why Request-Response Thinking Breaks Down 🔗

The request-response model is beautiful in its simplicity. A client sends a request, the server does work, the server responds. The connection is open the whole time; if something fails, you get an exception; if everything succeeds, you get data back. It's easy to reason about because one thing happens at a time, in one place, under one transaction.

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: Request
    Server-->>Client: Response

Distribute that workflow across multiple services, though, and the guarantees evaporate fast. Consider an order fulfillment flow that calls three services: one charges the card, one reserves inventory, and one sends a confirmation email. If the inventory service fails after the card charge goes through, what state are you in? The database transaction that might have protected you in a monolith doesn't span service boundaries. Each service has already committed its own local transaction. You can't "rollback" a charge that's already been authorised. You can't "un-send" an email.

sequenceDiagram
    participant Client
    participant OrderService as Order Service
    participant PaymentService as Payment Service
    participant InventoryService as Inventory Service
    participant EmailService as Email Service

    Client->>OrderService: POST /orders
    activate OrderService
    OrderService->>PaymentService: Charge card
    PaymentService-->>OrderService: ✓ Authorised
    OrderService->>InventoryService: Reserve stock
    InventoryService-->>OrderService: ✗ Out of stock
    Note over PaymentService: Card already charged
    Note over EmailService: Never reached
    OrderService-->>Client: 500 Error
    deactivate OrderService

What you get instead is partial completion - a system where some steps succeeded, some failed, and the overall state is inconsistent in ways that are not immediately obvious. And this isn't a corner case you can architect away. Services fail mid-flight. Networks drop connections. Deployments happen. The question isn't whether partial completion will occur; it's whether your system knows how to recover when it does.

There's also the state drift problem. In a long-running workflow, every service involved maintains its own view of the process state. If those views diverge - because a message was lost, a retry was missed, or a timeout fired at the wrong moment - you end up with services that disagree about where the workflow is. The payment service thinks the order is complete. The inventory service thinks it was cancelled. Nobody is wrong according to their own data. The system is just inconsistent.

Sagas: A Fast Recap 🔗

The Saga pattern was formalised by Hector Garcia-Molina and Kenneth Salem back in 1987, originally in the context of long-lived database transactions. The core idea is simple: instead of one large distributed transaction that would require coordination across all participants (which doesn't scale and is largely impractical in practice), you break the workflow into a sequence of smaller local transactions, each of which commits independently. And for each of those steps, you define a compensating transaction - a business action that semantically reverses what that step did, should something go wrong later.

If step 4 fails in a five-step workflow, you run the compensating transactions for steps 3, 2, and 1 in reverse order. You end up in a state that's consistent again - not identical to where you started (the compensation itself is a new business event), but coherent.

That's the pattern in one paragraph. Two things to hold onto: the sequence of local commits, and the compensations that undo them. Everything else - orchestration vs choreography, timeout handling, observability - is about how you implement that idea well in production.

Designing the Saga: Orchestration vs Choreography 🔗

There are two ways to coordinate a saga, and choosing the wrong one for your context creates pain that's hard to unwind.

Orchestration means there's a central coordinator - a saga state machine or process manager - that drives each step. It sends commands to services, waits for responses, tracks the overall state, and decides what happens next. The workflow logic lives in one place. If you need to know where a given order is in the fulfillment process, you ask the coordinator. This is intuitive. It maps well onto how humans think about workflows, and it makes complex compensations straightforward to implement because the coordinator has the full context.

Orchestration - workflow logic lives in the coordinator:

flowchart TD
    C([Coordinator])
    C -->|1. ChargeCard| P[Payment]
    C -->|2. ReserveStock| I[Inventory]
    C -->|3. CreateShipment| S[Shipping]

Choreography means there's no central coordinator. Each service reacts to events published by previous steps. Service A completes its work and publishes OrderValidated. Service B subscribes to that event, does its part, and publishes StockReserved. Service C picks that up and publishes PaymentProcessed. The workflow emerges from the interactions - no single service orchestrates it. This scales better, removes a central point of coupling, and lets each team own their domain completely.

Choreography - workflow emerges from events, no coordinator:

sequenceDiagram
    participant P as Payment
    participant I as Inventory
    participant S as Shipping

    Note over P,S: No coordinator — services react to events
    P-)I: OrderPaid
    I-)S: StockReserved
    S-)P: ShipmentCreated

So how do you choose? I look at a few things. If the workflow has complex branching logic - "if the payment fails, route to retry; if the retry budget is exhausted, escalate to manual review; if manual review times out, cancel and notify" - that logic has to live somewhere. In choreography, it ends up scattered across services that need to know about each other's states, which tends to create hidden coupling. Orchestration keeps it in one place. On the other hand, if the steps are genuinely independent domain reactions - each service truly just needs to know "this thing happened, now I do my part" - choreography gives you better isolation and resilience.

Where I see teams go wrong is mixing both styles within a single workflow. An orchestrator that also listens to events from services it's supposed to be coordinating creates a tangle. Pick one model per workflow, and be deliberate about it. Choreography is not "orchestration without writing a coordinator" - it's a different design choice with different trade-offs.

Compensating Transactions Done Right 🔗

Here's the thing that trips up almost every team the first time they design a saga: compensation is not rollback. They look similar on the surface - something went wrong, we go back to where we were - but they're fundamentally different operations.

Rollback is a database primitive. When a transaction fails, the database engine atomically reverses every change as if the transaction never happened. It's invisible to the business. It cannot fail. It's symmetric - the before and after states are identical.

Compensation is a business action. Issuing a refund is not "un-charging" a card - it's a new transaction that creates a new fact in the payment ledger. Cancelling a reservation is not "un-reserving" inventory - it's releasing stock back to the available pool, which may then be picked up by another order. Sending a cancellation email is not "un-sending" the confirmation - it's a new message with a new meaning. Compensation can fail. It can be partial. It's visible to the business and to the customer.

This matters because if you design compensations as if they were rollbacks, you'll miss important cases. The most important question to ask when designing a compensating transaction is: "What if this compensation fails?" Most teams never ask it. A failed compensation is its own error case that needs its own handling - possibly a manual intervention workflow, an alert to an operations team, or a retry with a longer delay.

Design compensations upfront, not as afterthoughts. For every step in your saga, before you write the forward path, write the compensating action. Name it explicitly: RefundPayment, ReleaseReservation, SendCancellationNotification. Some steps won't have a neat compensation - sending an SMS is very hard to undo. Model those as non-compensatable steps and think carefully about where in the saga sequence they appear.

Every compensating transaction must also be idempotent. When your saga state machine executes a compensation, it might execute it more than once - due to a retry after a timeout, or a network blip that prevented the acknowledgment from reaching the coordinator. Executing the same compensation twice must produce the same result as executing it once. The refund must not be issued twice. The reservation must not be released twice and then fail on a third attempt. Design for this from the start, not after you find the bug in production.

Timeouts, Retries, and the Messy Middle 🔗

Long-running workflows spend a lot of time in a state I call the messy middle: you've sent a command to a service, and you don't know what happened to it.

The message might have been delivered and processed successfully but the acknowledgment was lost in transit. The message might never have arrived at all. The service might have received it, started processing, crashed halfway through, and is now recovering. The service might have processed it and responded, but your network blipped and you missed the response. From the saga coordinator's perspective, all of these look identical: silence.

sequenceDiagram
    participant C as Coordinator
    participant S as Service

    Note over C,S: Scenario A — message never arrived
    C--xS: Command
    C->>C: ⏱ Timeout

    Note over C,S: Scenario B — service crashed mid-processing
    C->>S: Command
    Note over S: Crash
    C->>C: ⏱ Timeout

    Note over C,S: Scenario C — acknowledgment lost
    C->>S: Command
    Note over S: ✓ Processed
    S--xC: Ack
    C->>C: ⏱ Timeout

    Note over C: All three look identical to the coordinator

This is the fundamental challenge that makes distributed systems hard. The timeout fires, and you need to make a decision: did that step complete or not?

The answer is almost always: assume it might have completed, and design your retry as if it did. Send the same command again with the same idempotency key. A well-designed service will recognise the duplicate and return the result of the first execution without re-processing. A poorly designed service will execute the operation twice. This is why idempotency isn't optional in saga steps - it's the mechanism that makes the messy middle safe to navigate.

For retry policies within sagas, I think in terms of three categories. Transient failures - network blips, brief overloads - should be retried quickly, with exponential backoff and jitter to avoid thundering-herd effects. Uncertain states - where you timed out and don't know the outcome - should be retried with idempotency keys. Permanent failures - a 400 Bad Request, a business rule violation, an external service that's permanently shut down - should not be retried at all. Retrying a permanent failure is just executing the same bug repeatedly.

Timeout policies should be defined per step, based on that step's expected latency SLA. Don't use a single global timeout for everything - a warehouse reservation might legitimately take 30 seconds while a payment authorisation should complete in under 3. When a timeout fires in a saga, you have three options: retry the step, escalate to manual review, or start the compensation sequence. Which one you choose depends on the business rules - and those rules should be explicit in your saga design, not emergent from whatever happens to work in tests.

Observability: Seeing Inside the Black Box 🔗

A long-running workflow that spans multiple services and days of calendar time is, without the right observability, a black box. You know when it started, and you know when it ends. Everything in between is inference.

The most important thing you can do is establish a correlation ID from the very first event, and propagate it through every message, every log line, every trace span for the entire lifetime of the workflow. The correlation ID ties together every bit of activity - the payment charge, the inventory update, the shipping label generation - into a single coherent narrative. Without it, debugging a workflow failure means manually correlating timestamps across five services' logs, which is miserable and error-prone.

Beyond correlation, you need saga state snapshots - a persistent record of what state the saga is in at each point in time. Every time the saga transitions - a step completes, a timeout fires, a compensation begins - record that transition with a timestamp. This gives you a queryable audit log: "where is order 12345 in the workflow right now?" and "what was the sequence of events that led to this saga being stuck in the compensation phase?" A good saga state machine will handle this automatically; if you're rolling your own, it's the first thing to build.

Think about what you need to monitor operationally:

How many saga instances are currently in-flight, by workflow type and by state?
What's the p99 completion time for each workflow type, and how has it changed over time?
How many sagas are currently stuck - in a state they haven't left for longer than expected?
What's the rate of compensations being triggered, and which saga steps are causing them most often?

That last metric is particularly valuable. If you start seeing a spike in compensations triggered from a specific step, that step is degrading. You can catch this before it turns into a customer-visible incident.

Five Things Worth Remembering 🔗

Model the unhappy paths first. The happy path is easy - services cooperate, everything succeeds. The value of saga design is in making failure explicit: defining what "undo step 3" means as a named business operation before you write step 3.
Compensation is not rollback. It's a new forward action with its own failure modes. Ask "what if this compensation fails?" for every step, and have an answer.
Choose orchestration or choreography deliberately. Both are valid. Orchestration wins for complex branching and human-in-loop steps. Choreography wins for genuinely independent domain reactions. Mixing both within a single workflow is a sign you haven't committed to a model.
Every saga step must be idempotent. The messy middle is unavoidable in distributed systems. The mechanism that makes retries safe is idempotency, and it needs to be designed in from the start, not retrofitted.
Observability is not optional. A workflow you can't see is a workflow you can't operate. Correlation IDs, state snapshots, and operational metrics are the minimum.

Whatever your stack - MassTransit, NServiceBus, Temporal, AWS Step Functions, or something you've built yourself - these patterns apply. The frameworks help with the plumbing, but the design thinking is on you.

If any of this resonates with problems you're currently dealing with, or if you disagree with any of my choices here, reach out. I'd genuinely like to hear how your team has approached it.

PS: Let me know if I forgot anything.

Keep Your Claude Code Agents Out of the Team's Repo

2026-04-06T00:00:00Z

Your Claude Code setup is yours. Your team's repo shouldn't have to carry it.

You've spent time building up a nice set of Claude Code agents and skills. Custom reviewers, project-specific helpers, the kind of thing that makes your day a bit smoother. Then you open a pull request and realise: that .claude/ folder is sitting right there in the diff, ready to land in a shared repository that your whole team owns.

Now you have a decision to make, and neither option feels great.

The Problem With the Obvious Choices 🔗

You can commit your .claude/ folder to the repo. It works. But now you're adding personal AI tooling to a shared codebase that your team didn't ask for, and the next time a colleague clones the repo they get your configuration whether they want it or not. That's not a disaster, but it's noise - and noise compounds.

The other option is to leave it local. Simple. Except local means you lose it the moment you switch machines, rebuild your environment, or hand this work off to someone else. Local-only configuration doesn't travel with you.

There's a third path that most people don't think of: keep your agents and skills in a separate, private repository and use symbolic links to make Claude discover them as if they lived inside each project.

The Setup: One Config Repo, Many Projects 🔗

The idea is straightforward. Instead of scattering .claude/ folders across every repo you work in, you maintain a single claude-configs repository that mirrors your project structure. Each project gets a folder in there, and your actual project repos get a symlink that points back to it.

Let's take a childish example to make it concrete. Say you have two projects: my-api and my-worker. Your layout ends up looking like this:

workspace/
  my-api/                  ← shared, committed, team-owned
  my-worker/               ← shared, committed, team-owned
  claude-configs/          ← private, yours, committed to your own repo
    my-api/
      .claude/
        agents/
        skills/
    my-worker/
      .claude/
        agents/
        skills/

Claude Code sees my-api/.claude/agents/ and reads your agents from it. It has no idea - and doesn't need to know - that the folder is actually a symlink into claude-configs.

Step 1 - Create the Config Repo 🔗

Start by creating the structure and moving your existing agents and skills over.

mkdir claude-configs
cd claude-configs
git init

mkdir -p my-api/.claude/agents
mkdir -p my-api/.claude/skills
mkdir -p my-worker/.claude/agents
mkdir -p my-worker/.claude/skills

Then copy your existing agents and skills into their new home (run these from your workspace/ root, not from inside claude-configs):

cp -r my-api/.claude/agents/* claude-configs/my-api/.claude/agents/
cp -r my-api/.claude/skills/* claude-configs/my-api/.claude/skills/

Now the source of truth lives in claude-configs. Your projects will just point to it.

Step 2 - Replace the Folders With Symlinks 🔗

Remove the real folders from your project and replace them with symbolic links.

On Linux, macOS, or WSL:

cd my-api

# Remove the original folders (content is already in claude-configs)
rm -rf .claude/agents .claude/skills

# Create the symlinks
ln -s ../../claude-configs/my-api/.claude/agents .claude/agents
ln -s ../../claude-configs/my-api/.claude/skills .claude/skills

On Windows (PowerShell - requires Developer Mode or Administrator):

cd my-api

Remove-Item -Recurse -Force .claude\agents, .claude\skills

New-Item -ItemType SymbolicLink -Path ".claude\agents" -Target "..\..\claude-configs\my-api\.claude\agents"
New-Item -ItemType SymbolicLink -Path ".claude\skills" -Target "..\..\claude-configs\my-api\.claude\skills"

Use absolute paths on Windows if relative paths give you trouble. The target has to exist before you create the link, so make sure claude-configs is set up first.

Step 3 - Hide the Symlinks From Git, Without Touching .gitignore 🔗

Here's the part that trips people up. If you add .claude/agents to .gitignore, that file gets committed and your teammates see it. That's exactly what we're trying to avoid.

The right tool is .git/info/exclude. It behaves like .gitignore but it's machine-local and never committed. Your colleagues will never know it exists.

# Inside my-api
echo ".claude/agents" >> .git/info/exclude
echo ".claude/skills" >> .git/info/exclude

On Windows, Git sometimes treats directory symlinks as a single file entry rather than a directory. Add both forms to cover your bases:

.claude/agents
.claude/agents/
.claude/skills
.claude/skills/

Then verify:

git status

The agents/ and skills/ folders should not appear. If they do, double-check the entries in .git/info/exclude - a typo there is the usual culprit.

Step 4 - Commit the Config Repo 🔗

cd claude-configs
git add .
git commit -m "Add Claude agents and skills for my-api and my-worker"
git remote add origin <your-private-repo-url>
git push -u origin main

You now have version history, a backup, and a clean way to reproduce your setup on any machine. Clone claude-configs, re-run the ln -s commands, and you're back to where you were.

Day-to-Day Workflow 🔗

Once it's running, you mostly forget it's there. You edit files in claude-configs, commit inside that repo, and the changes are immediately visible through the symlink. No sync step, no copy-paste.

Action	Where
Edit an agent or skill	`claude-configs/my-api/.claude/agents/`
Save changes	`git commit` inside `claude-configs`
Use on a new machine	Clone `claude-configs`, re-run the `ln -s` commands
Add a new project	Create the folder in `claude-configs`, symlink, exclude

Why `.git/info/exclude` and not `.gitignore` 🔗

This deserves a proper answer because the difference matters.

	`.gitignore`	`.git/info/exclude`
Committed to repo	Yes	No
Affects teammates	Yes	No
Reversible without a commit	No	Yes

.gitignore is a shared agreement between everyone on the team. When you add something there, you're making a statement on behalf of the project. .git/info/exclude is for exactly this kind of case: personal, local configuration that is nobody else's business.

A Note for Windows Users 🔗

Windows requires Developer Mode or an Administrator terminal to create symlinks. If you get an access error, that's why.

You also need to make sure Git is configured to handle symlinks correctly:

git config --global core.symlinks true

Without this, Git may check out a symlink as a plain text file containing the target path as a string. The folder won't exist, Claude won't find anything, and you'll spend twenty minutes wondering what went wrong. Set it once, globally, and move on.

Credit 🔗

This pattern is adapted from Tamir Dresher's approach to using GitHub Copilot's agent framework without touching shared repositories. The same idea maps cleanly onto Claude Code's .claude/agents and .claude/skills structure.

Your tooling is part of how you work, not part of what the team ships. Keeping those things separate has always been the right instinct - symlinks just make it practical.

Your Database Can't Read. Vector Databases Can.

2026-03-30T00:00:00Z

Vector databases are everywhere right now. Before you add one to your architecture, it is worth understanding what problem they actually solve.

The Search Problem Nobody Talks About 🔗

Think about it - when you search for "cheap hotels near the beach", a traditional database has no idea what you mean. It looks for rows where columns contain the words "cheap", "hotels", "near", "beach". Exact matches, maybe with some LIKE wildcards. It is matching characters, not meaning.

That works fine for structured queries. "Give me all orders where status = 'pending'" - a relational database handles that brilliantly. But the moment your search depends on meaning rather than exact text, you are fighting the tool.

This is the gap vector databases fill. They do not store rows and columns. They store meaning.

What Is a Vector, Really? 🔗

A vector is just a list of numbers. That is it. But those numbers are meaningful - they are the output of a machine learning model trained to capture the semantic content of whatever you fed it.

Give a text embedding model the sentence "the cat sat on the mat" and you will get back something like [0.12, -0.87, 0.45, ...] - hundreds or thousands of numbers. Feed it "a kitten rested on the rug" and you will get a different list, but one that is close to the first one in mathematical space. The model learned that cats and kittens are related, that sitting and resting are similar, that mats and rugs belong to the same world.

This is the core idea: things that mean similar things end up near each other in vector space. And "near" is something we can compute very fast.

The same principle works for images, audio, code snippets, user behaviour - anything you can run through a model that produces embeddings.

How Similarity Search Actually Works 🔗

Once you have vectors, finding the most similar ones is a geometry problem. The most common approach is cosine similarity - measuring the angle between two vectors. Two vectors pointing in roughly the same direction are semantically similar. Two vectors pointing in opposite directions are not.

In theory you could compare a query vector against every stored vector. At a thousand entries, that is fine. At a million, it is slow. At a billion, it is not going to work.

This is where indexing algorithms come in. HNSW (Hierarchical Navigable Small World) is the most widely used - it builds a graph structure that lets you skip most of the search space and find approximate nearest neighbours in milliseconds. The trade-off is that it is approximate - you might miss the single closest match in exchange for speed. In practice, for most use cases, the top 5 results from an approximate search are indistinguishable from the exact top 5.

Simply put: vector databases are optimised for this specific operation in a way general-purpose databases are not. You can store vectors in PostgreSQL and compute cosine similarity with pgvector. For moderate scale, that works well. But a dedicated vector database gives you purpose-built indexing, filtering, and metadata handling that a SQL extension cannot match at scale.

One thing worth naming explicitly: your existing ORM does not know what cosine similarity is. Entity Framework Core, Dapper, whatever you use - none of it has a concept of "find me the rows most similar to this query". This is not a gap in those tools; it is a different paradigm entirely. The mental model shift from "find this exact thing" to "find things similar to this thing" is the hardest part of adding vector search to an existing system - not the database choice.

RAG: The Use Case That Made Vector DBs Famous 🔗

If you have worked with LLMs, you have probably heard of Retrieval-Augmented Generation. The problem it solves: LLMs have a knowledge cutoff. They do not know your internal documentation, your latest product specs, your customer's order history. And you cannot dump it all into the prompt - context windows have limits, and at scale this gets expensive fast.

The solution: store that knowledge as embeddings in a vector database. When a user asks a question, convert the question to a vector, find the most relevant chunks from your database, and inject them into the prompt. The LLM answers based on your data, not just its training.

This is why every AI feature announcement mentions vector databases right now. They are the memory layer for LLM-powered applications.

But RAG is not the only use case worth knowing about.

Other Use Cases Worth Knowing 🔗

Semantic search is the obvious one - search that understands meaning. "Show me articles about concurrency issues" finds posts about race conditions and deadlocks even if they do not contain those exact words.

Recommendation systems are another strong fit. If you embed your products and your users' purchase history into the same vector space, you can find "users whose taste is similar to this user" or "products similar to this one" with a nearest-neighbour query.

Anomaly detection works similarly - embed your normal traffic patterns, then flag incoming requests whose vectors are far from any known cluster. Duplicate detection, image search, code similarity - they all reduce to the same operation: embed, store, query by proximity.

The Landscape: Which One Do You Pick? 🔗

Here is a quick honest comparison of the options you will actually encounter:

Pinecone - fully managed, serverless pricing, minimal ops overhead. Good if you want to ship fast and do not want to think about infrastructure. Vendor lock-in is real.
Qdrant - open source, written in Rust, excellent performance. My personal preference for self-hosted setups. Great filtering support and a clean API, plus an official .NET SDK (Qdrant.Client).
Weaviate - open source, schema-oriented, supports hybrid search (vector + keyword) out of the box. Good if you need both semantic and structured queries in one place.
Chroma - lightweight, easy local setup, popular for prototypes and small projects. Not what you would put in front of production traffic at scale.
pgvector - a PostgreSQL extension. If you already run Postgres and your scale is moderate (think hundreds of thousands of vectors, not hundreds of millions), this is often the pragmatic choice. No new infrastructure, no new operational complexity, familiar tooling. With Pgvector.EntityFrameworkCore you get a Vector column type and LINQ methods like CosineDistance() and L2Distance() - you can be running similarity queries in EF Core in an afternoon.

In my opinion, the biggest mistake teams make is reaching for Pinecone or Qdrant before they have validated that pgvector cannot handle their load. For most .NET teams already on Postgres/EF Core, pgvector is the right first step. The dedicated vector database conversation should happen at scale, not day one.

What This Means in Practice 🔗

If you are evaluating vector databases, a few things are worth keeping in mind.

Your embeddings are only as good as your model. A bad embedding model produces vectors where similar things end up far apart - no indexing algorithm fixes that. Test your retrieval quality before committing to a database choice.

Embeddings go stale. If your underlying data changes, the vectors need to be regenerated. This is an operational concern most architecture diagrams skip over.

Hybrid search matters. Pure semantic search sometimes misses exact matches (product SKUs, proper nouns, IDs). Most real production systems combine vector similarity with keyword search. Some databases (Weaviate, Elasticsearch with kNN) support this natively; others you wire up yourself.

And finally - you do not need a vector database to use embeddings. If you are building a small RAG prototype, start with pgvector or even SQLite with a vector extension. Add the dedicated infrastructure when you have a reason to.

Useful .NET Tools and Packages 🔗

If you are building on .NET, these are the packages and tools you will reach for:

Pgvector.EntityFrameworkCore - adds Vector column type to EF Core with CosineDistance() and L2Distance() LINQ methods. Start here if you are already on Postgres.
Qdrant.Client - official Qdrant .NET SDK for working with a dedicated Qdrant instance.
Microsoft.SemanticKernel.Connectors.Qdrant and Microsoft.SemanticKernel.Connectors.Postgres - Semantic Kernel connectors for using Qdrant or pgvector as the vector store in an SK-based application.
Memorizer - a .NET service that gives AI agents persistent semantic memory using pgvector. Supports workspaces, tagging, versioning, knowledge graph relationships between memories, and a web UI. Ships as a Docker image and exposes an MCP server, so any MCP-compatible agent can use it as a memory layer out of the box.

Closing 🔗

Vector databases are a genuine new primitive in the software stack, not just AI hype with a database attached. They solve a real problem - matching by meaning, at scale - that relational databases were never designed for.

But like any tool, the question is not "should I use a vector database?" It is "does my problem require this, and at what scale?" Start simple. Measure. Add complexity when the simpler thing runs out of road.

Async Does Not Mean Scalable

2026-03-04T00:00:00Z

We keep hearing about async/await syntactic sugar and message queues and they make our applications faster, more responsive, more scalable. Teams rewrite synchronous endpoints to async ones and feel better about the decision. And when that's not enough, someone adds a message queue — and suddenly the system feels fixed.

But what if it wasn't broken in the way you thought?

The Reflex 🔗

Every system that starts struggling under load goes through the same ritual. Traffic climbs, latency spikes, and someone in the room says: "let's make it async." The team nods. It sounds right. And for a while, it works — or at least, the dashboard stops screaming.

Then the queue backs up. Or the thread pool saturates. Or the database starts timing out. And the team discovers that async didn't fix the problem. It just changed where the problem lived.

This isn't a criticism of async/await or message queues. They're genuinely useful - especially the message queues . But there's a persistent confusion in how teams reach for them — as a scaling tool rather than a decoupling tool — and it leads to systems that feel fast right up until they don't.

Why async feels like a scaling solution 🔗

Imagine a restaurant where the kitchen is slow. Orders pile up, customers wait, tables sit occupied for too long.

Someone has an idea: hire a host to take orders at the door and give customers a buzzer. Now people don't stand in line at the counter — they sit down, browse their phones, and the kitchen calls them when food is ready. The entrance is clear. The restaurant feels more efficient.

But the kitchen is still slow. The same number of meals gets cooked per hour. The queue just moved from the door to the pager system — and now it's harder to see.

This is exactly what happens when you reach for async/await or a message queue as a scaling solution.

What async/await actually does 🔗

When you await an HTTP request or a database call in .NET, the current thread is released back to the thread pool while the work happens. Once it completes, the continuation resumes on another thread.

public async Task<Order> GetOrderAsync(int id)
{
    // Thread is released here while the DB query runs
    return await _db.Orders.FindAsync(id);
}

That's genuinely useful. In ASP.NET Core, a server handling thousands of concurrent I/O-bound requests with a small thread pool instead of spinning up thousands of threads is a better server. It's the right answer to thread pool exhaustion.

But notice what async doesn't do: it doesn't make the database query faster. It doesn't reduce the number of queries. If 1,000 requests come in simultaneously, the database still gets 1,000 queries — they just don't each hold a thread while waiting.

The thread is free. The work is not.

What adding a queue does 🔗

The queue is a debt counter, not a buffer

Adding a message queue feels like a more decisive fix. The API returns instantly. Traffic spikes are absorbed. The team ships it and calls it done.

But every message still needs a consumer. The consumer still hits the database, calls the downstream service, runs the business logic. What changed is where the pressure accumulates.

Think of it like a debt. If your producer sends 1,000 messages per second and your consumer handles 200, you're accumulating 800 messages of debt every second. After ten minutes: 480,000 unprocessed messages. The producer side looks fine. The queue is quietly growing.

When will you notice? When redelivery storms start hitting your consumer. When messages expire. When the lag is hours, not seconds.

xychart-beta
    title "Queue debt over time (producer: 1000/s, consumer: 200/s)"
    x-axis ["0m", "2m", "4m", "6m", "8m", "10m"]
    y-axis "Unprocessed messages" 0 --> 500000
    bar [0, 96000, 192000, 288000, 384000, 480000]

The bottlenecks async doesn't touch 🔗

In my experience, most throughput and scalability problems aren't thread problems at all. They're resource contention problems — and no amount of concurrency management fixes a contention problem:

Database connection pool — finite by design. Callers queue for a connection whether the calling code is async or not.
Row-level locks — concurrent writers serialize. An await doesn't skip the queue.
External rate limits — the third-party API that allows 100 requests per second doesn't care that your code is elegant.
Shared mutable state — still needs coordination. The concurrency model doesn't change because you added async.

Making the calling code async moves the problem one layer down. It doesn't remove it — it just makes it harder to see because you've separated the producer from the consumer.

When to actually reach for async 🔗

None of this is a reason to avoid async/await. It's a reason to reach for it for the right reason: genuine thread pool pressure in high-concurrency I/O-bound workloads.

Message queues have their place too — decoupling services with different uptime requirements, absorbing traffic spikes without dropping requests, building retry logic for unreliable operations. These are real problems worth solving.

Just don't confuse those benefits with throughput. Decoupling and throughput are different properties. A well-decoupled system can still be slow. A fast system doesn't require a queue.

What actually improves throughput 🔗

When throughput is the real problem, the levers are different:

More consumer instances — horizontal scaling works when consumers are stateless and independent. If processing one message takes 50ms and you need to handle 500 messages/second, you need at least 25 concurrent consumers. Spin up more; the math is simple.
Partitioning — route work by a meaningful key (customer ID, tenant ID) so consumers operate on non-overlapping subsets without competing for the same rows. This is where real parallelism comes from.

graph LR
    Q[Queue] -->|customer A–M| C1[Consumer 1]
    Q -->|customer N–Z| C2[Consumer 2]
    C1 --> DB1[(DB shard 1)]
    C2 --> DB2[(DB shard 2)]

Keeping handlers lean — shared mutable state limits how many you can run in parallel. A handler that locks a shared cache or calls a single-instance service will serialize regardless of how many instances you run.

And measure the right thing. Consumer lag, not queue depth. Queue depth is a snapshot — it tells you how much work is waiting right now. Consumer lag tells you how fast you're falling behind. One is a count. The other is a velocity. You need the velocity to plan capacity.

async/await, scalability, and what to do instead 🔗

async/await is a thread management tool. Message queues are a decoupling tool. Neither is a throughput tool on its own.

If your system is slow, profile before you refactor. Measure before you add infrastructure. The database index you're not adding, the N+1 query you haven't noticed, the downstream service with no timeout — these are more likely your problem than the absence of await.

Async shifts the work. Scale requires designing where the work goes.

If this resonates with you, share it with someone who just added a queue to a slow service and called it a day. I'd love to hear your thoughts — find me on LinkedIn and drop a comment.

OpenTelemetry in C#: Setup, Spans, and Custom Instrumentation

2026-02-07T00:00:00Z

OpenTelemetry in C#: Setup, Spans, and Custom Instrumentation 🔗

If you've landed here directly, consider reading Part 1 first. It covers what OpenTelemetry is, what traces, metrics, and logs actually mean, and why the instrumentation/exporter separation matters. This post picks up right where that one ends - concepts assumed, code begins.

OpenTelemetry C# Setup in ASP.NET Core 🔗

Enough theory. Let's get something running.

Add the NuGet packages:

dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Instrumentation.Http
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Wire it up in Program.cs:

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .SetResourceBuilder(ResourceBuilder.CreateDefault()
            .AddService("my-api", serviceVersion: "1.0.0"))
        .AddAspNetCoreInstrumentation()   // auto-traces every incoming HTTP request
        .AddHttpClientInstrumentation()   // auto-traces outgoing HttpClient calls
        .AddSource("MyApp.Orders")        // register your custom ActivitySource
        .AddOtlpExporter())               // ship traces to Jaeger or a collector
    .WithMetrics(metrics => metrics
        .AddAspNetCoreInstrumentation()
        .AddRuntimeInstrumentation()      // GC, thread pool, memory - free signal
        .AddMeter("MyApp.Orders")         // register your custom Meter
        .AddOtlpExporter())
    .WithLogging(logging => logging
        .AddOtlpExporter());

That's the complete wiring. The ASP.NET Core instrumentation alone gives you traces for every incoming HTTP request and all outgoing HttpClient calls - zero manual code required. Add OpenTelemetry.Instrumentation.SqlClient if you want SQL queries in there too.

Now spin up Jaeger locally:

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

Open http://localhost:16686. Start your application, hit any endpoint, refresh Jaeger. You'll see your first trace - a complete timeline of what happened inside your API for that single request. That moment is genuinely satisfying.

To configure the OTLP exporter endpoint explicitly:

.AddOtlpExporter(opts =>
{
    opts.Endpoint = new Uri("http://localhost:4317");
    opts.Protocol = OtlpExportProtocol.Grpc;
})

Custom Spans 🔗

Auto-instrumentation covers the framework-level operations: the HTTP request arrived, the SQL query ran, the HttpClient call went out. Useful - but it knows nothing about your business logic.

A custom span lets you draw your own box around any operation that matters to you. When you start a span, the clock starts. When the using block exits - whether normally or because an exception was thrown - the span closes and its duration is recorded. Everything that happens inside that block - child spans, log lines, events - is linked together by the same TraceId.

You control the name ("PlaceOrder"), the attributes (customer.id, order.id), and the status (OK or ERROR). This is where generic "OpenTelemetry" becomes your telemetry - shaped around the operations that actually matter in your domain.

public class OrderService
{
    private static readonly ActivitySource Source = new("MyApp.Orders");
    private readonly ILogger<OrderService> _logger;

    public OrderService(ILogger<OrderService> logger) => _logger = logger;

    public async Task<Order> PlaceOrderAsync(int customerId, int productId)
    {
        using var activity = Source.StartActivity("PlaceOrder");
        activity?.SetTag("customer.id", customerId);
        activity?.SetTag("product.id", productId);

        try
        {
            _logger.LogInformation("Placing order for customer {CustomerId}", customerId);

            var inventory = await CheckInventoryAsync(productId);
            if (!inventory.Available)
            {
                activity?.SetStatus(ActivityStatusCode.Error, "Out of stock");
                activity?.AddEvent(new ActivityEvent("inventory.unavailable"));
                throw new InvalidOperationException("Product out of stock");
            }

            var order = await CreateOrderAsync(customerId, productId);
            activity?.SetTag("order.id", order.Id);
            return order;
        }
        catch (Exception ex)
        {
            activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
            throw;
        }
    }

    private async Task<InventoryResult> CheckInventoryAsync(int productId)
    {
        using var activity = Source.StartActivity("CheckInventory");
        activity?.SetTag("product.id", productId);
        // database call
        return new InventoryResult(Available: true);
    }
}

A few things worth knowing here:

ActivitySource is static readonly - create it once, reuse it everywhere across the lifetime of the application
The using on activity ensures the span closes (and its duration is recorded) when the block exits, even on exception
Tags via SetTag become searchable attributes in your backend - filter traces by customer.id or order.id directly in Jaeger's UI
SetStatus(ActivityStatusCode.Error) marks the span red in the Jaeger UI, making failures immediately obvious in the trace timeline
AddEvent adds a timestamped annotation to the span - useful for checkpoints inside a long operation ("inventory checked", "payment initiated")

The child span CheckInventory automatically becomes a child of PlaceOrder because OTel tracks the ambient activity context via AsyncLocal. You don't pass parent IDs manually - it just works across await boundaries.

Custom Metrics 🔗

public class OrderMetrics
{
    private static readonly Meter Meter = new("MyApp.Orders", "1.0.0");

    private readonly Counter<long> _ordersPlaced;
    private readonly Counter<long> _ordersFailed;
    private readonly Histogram<double> _orderProcessingTime;

    public OrderMetrics()
    {
        _ordersPlaced = Meter.CreateCounter<long>(
            "orders.placed",
            description: "Total number of orders placed");

        _ordersFailed = Meter.CreateCounter<long>(
            "orders.failed",
            description: "Total number of failed orders");

        _orderProcessingTime = Meter.CreateHistogram<double>(
            "orders.processing_duration_ms",
            unit: "ms",
            description: "Time to process an order end-to-end");
    }

    public void RecordOrderPlaced(string region) =>
        _ordersPlaced.Add(1, new KeyValuePair<string, object?>("region", region));

    public void RecordOrderFailed(string reason) =>
        _ordersFailed.Add(1, new KeyValuePair<string, object?>("reason", reason));

    public void RecordProcessingTime(double ms) =>
        _orderProcessingTime.Record(ms);
}

Register OrderMetrics as a singleton in DI and inject it into OrderService. Now you have business-level signal - not just "endpoint returned 200" but "347 orders processed in the last minute, 4 failed, p99 processing time was 430ms."

The region parameter on RecordOrderPlaced is an attribute on the metric data point. It lets you slice the counter: "EU orders" vs "US orders". Watch cardinality here - don't use a user ID or request ID as an attribute or you'll create millions of unique time series and make your metrics backend very unhappy.

Log Correlation - Nothing to Change 🔗

When you emit a log inside an active span, OTel automatically enriches it with TraceId and SpanId:

public async Task ProcessAsync()
{
    using var activity = Source.StartActivity("Process");

    // Both log lines automatically carry TraceId and SpanId - no changes needed
    _logger.LogInformation("Processing started");
    await DoWorkAsync();
    _logger.LogInformation("Processing completed");
}

With a structured logger (Serilog, for example), the output looks like:

{
  "message": "Processing started",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7",
  "timestamp": "2026-04-03T14:32:05.123Z"
}

When you spot an error in your log aggregator (Seq, Elasticsearch, Loki), copy the traceId, paste it into Jaeger's search, and you immediately see everything that was happening in the system when that log line was written. This is the connection between the three pillars that makes observability actually useful - any signal leads you to the others.

Where to Go Next 🔗

The OTel Collector - rather than shipping telemetry directly from your application to a backend, the Collector acts as a pipeline: your app sends to the Collector, the Collector fans out to multiple backends, applies filters, redacts sensitive fields, and batches efficiently. For anything beyond local development, this is the recommended architecture.

Sampling strategies - head-based sampling (decide at trace start) vs tail-based sampling (decide after the full trace is captured, so you can always keep error traces). The OTel Collector supports both. In development, sample 100%. In production, start at 10% and tune from there.

Cloud backends - Azure Monitor has supported OTLP natively since 2023. AWS X-Ray, Google Cloud Trace, Datadog, Dynatrace, New Relic, and Honeycomb all accept OTLP. Switching backends is one changed exporter configuration in Program.cs - your instrumentation code stays untouched.

More library instrumentation - there are OTel packages for Entity Framework Core, Redis, RabbitMQ, gRPC, MassTransit, and more. The pattern is always the same: one AddXInstrumentation() call in your setup.

The OpenTelemetry .NET documentation is thorough and the GitHub examples cover every major scenario.

Start Simple, Add Signal 🔗

You don't need to instrument everything on day one.

Start with auto-instrumentation for ASP.NET Core and HttpClient. Get traces into Jaeger. Spend five minutes clicking through a real trace from your application - look at what it already knows about your system without a single line of custom code.

Then add one custom span around the most important operation in your codebase - the thing that, when it is slow, everyone notices. Attach the domain attributes that matter: order IDs, customer IDs, the names of the external services you call.

That single span will pay for itself the first time something breaks at 2am and you can see exactly where to look.

Have you added OpenTelemetry to a .NET project? I'd love to hear what backend you're using and what surprised you. Drop a comment below or reach me on LinkedIn or X.

For more .NET deep-dives on ASP.NET Core, distributed systems, and architecture, check out the rest of the posts on irina.codes.

OpenTelemetry for Developers: The Concepts Explained Simply

2026-02-03T00:00:00Z

OpenTelemetry for .NET Developers: The Concepts Explained Simply 🔗

It's 2am. Your Phone is Ringing. 🔗

Production is down. The checkout flow is broken. Customers can't complete orders.

You open the logs. There are thousands of lines - INFO, DEBUG, ERROR messages from a dozen services - and none of them clearly say this is where it broke. You start guessing. Was it the payment service? The inventory API? The database connection pool? You SSH into servers, tail logs, grep for exceptions, and hope something jumps out.

Meanwhile, your on-call rotation is burning, your boss is messaging you, and every minute of downtime has a dollar value attached to it.

This is the problem observability solves. Not "do we have logs?" - you have plenty of those. The real question is: "can we actually understand what our system is doing from the outside?" That's a very different thing.

If you've never set up observability before - if words like "distributed tracing" or "metrics cardinality" make you glaze over - this post is for you. We'll start from first principles and use everyday analogies to make the concepts stick. The code comes in Part 2.

What is Observability? 🔗

Observability is a term borrowed from control theory. A system is "observable" if you can determine its internal state by examining its external outputs. For software, the question becomes: can you figure out what is happening inside your application by looking at the data it produces?

The classic alternative is monitoring - you set up dashboards and alerts for problems you know might happen. CPU over 90%? Alert. Error rate over 1%? Alert. Monitoring only tells you about problems you anticipated. Observability lets you ask new questions about your running system, even for failures you never predicted.

A good analogy is a visit to the doctor.

When you feel unwell, the doctor doesn't open you up to look inside. Instead, they gather external signals:

They ask you to describe your symptoms - "it hurts here, it started two days ago, it gets worse when I move" - that's your logs: a timestamped record of events that happened
They take your temperature, blood pressure, and heart rate - numbers tracked over time - that's your metrics: gauges and counters that show the system's health at a glance
They trace where the pain originates, step by step - that's your traces: the complete journey of a request through your system

OpenTelemetry is the industry-standard toolkit that lets your software produce all three signals in a consistent, vendor-neutral way. It is the second most active CNCF (Cloud Native Computing Foundation) project after Kubernetes - and that momentum is there for a reason.

Enter OpenTelemetry 🔗

OpenTelemetry (OTel) is a CNCF project born in 2019 from the merger of two earlier standards: OpenCensus (Google) and OpenTracing (community). The goal was to stop fragmenting the ecosystem. Before OTel, every vendor had their own SDK, their own agent, their own wire format. You'd instrument your app for Datadog, then decide to try Honeycomb, and find yourself rewriting everything.

OTel solves that by owning the instrumentation layer - the code that lives in your application and produces telemetry data. Where that data goes (Jaeger, Datadog, Azure Monitor, Honeycomb, Zipkin) is a separate concern, handled by swappable exporters. You change one line in Program.cs, not your entire codebase.

Think of it like a flight recorder - the black box on commercial aircraft. Every plane has one that records:

All notable events (logs)
Instrument readings every second (metrics)
The full flight path and timeline (traces)

The black box standard defines exactly what gets recorded, how it's encoded, and where it goes - so any airline (your application) can connect to any air traffic control system (any observability backend) without rebuilding the recorder. OTel is that standard for software.

One distinction worth locking in early: OpenTelemetry is not Jaeger. It is not Datadog. It is not your observability backend. Those tools store and visualize telemetry. OTel produces and ships it. This confusion derails a lot of developers when they first encounter the space.

What is Instrumentation? 🔗

Instrumentation is the act of adding code to your application that captures what is happening and turns it into data - traces, metrics, and logs.

Think of a busy kitchen in a restaurant. Without instrumentation, you just know that food goes in and plates come out. With instrumentation, you have a timer on every dish, a counter for every order, and a note every time something is returned. You can now answer questions you couldn't before: which dish takes the longest? When does the kitchen slow down? Which orders triggered a complaint?

There are two kinds of instrumentation:

Automatic instrumentation is when a library does the work for you. Packages like OpenTelemetry.Instrumentation.AspNetCore trace every incoming HTTP request, and OpenTelemetry.Instrumentation.Http traces every outgoing HttpClient call - without you writing a single line for each one. The library knows where the interesting things happen, so it instruments them on your behalf.

Manual instrumentation (or custom instrumentation) is when you do it yourself - for the parts that only you understand. No framework knows what a "PlaceOrder" operation is, or that you care about customer.id and order.id. That domain knowledge only lives in your code. In .NET, you reach for ActivitySource (for traces) and Meter (for metrics) from the System.Diagnostics namespace. More on that in Part 2.

The Three Pillars 🔗

Traces: The Parcel Tracker 🔗

When you order something online, you can track it. You see: picked up at warehouse - arrived at regional hub - out for delivery - delivered. Each step has a timestamp and a duration. If the parcel goes missing, you know exactly which step failed.

Distributed tracing works the same way for requests in your software.

A trace is the complete record of a single request's journey - from the moment it hits your API, through every service call, database query, cache lookup, and background job it touches, until a response goes back to the caller. Each individual step is called a span.

Every trace carries a TraceId that ties the whole journey together across all services. Every span carries its own SpanId and a ParentSpanId that links it back to whichever span called it - allowing you to reconstruct the exact call tree. Spans can also carry attributes (key-value pairs like customer.id or http.status_code) and events (timestamped annotations like "cache miss").

In .NET, the native API for this is System.Diagnostics.Activity and System.Diagnostics.ActivitySource - designed to be OTel-compatible from the start. In OTel terms: Activity = Span, ActivitySource = Tracer.

Metrics: The Car Dashboard 🔗

Your car doesn't send you a notification every time a cylinder fires or the alternator charges the battery. You get a dashboard: RPM, speed, fuel level, engine temperature. Numbers that summarize the state of the system so you can glance at them while driving.

Metrics do the same for your application.

Metrics are numbers measured or aggregated over time. Unlike traces (which follow individual requests) or logs (which capture individual events), metrics are cheap to store, fast to query, and easy to alert on. You don't record every request - you record the count, the rate, the percentile distribution.

The OTel SDK defines four instrument types: a Counter (only increases - total orders placed), an UpDownCounter (increases or decreases - active connections), a Histogram (distribution of values - request duration, giving you p50/p95/p99), and an ObservableGauge (polled at collection time - current memory usage). In .NET, these map directly to System.Diagnostics.Metrics.Meter and its family of types, available since .NET 6.

Logs: The Ship's Logbook 🔗

A ship's captain keeps a logbook. Every notable event goes in, in order: "14:32 - departed port", "15:10 - storm began", "16:45 - storm passed". A chronological record of what happened and when. When something goes wrong, you read the logbook.

Your application's logs work the same way. The problem in distributed systems is context: you have log lines from five services, all interleaved by timestamp, with no way to tell which lines belong to the same user request.

OTel solves this cleanly. When you emit a log inside an active span, OTel automatically injects the TraceId and SpanId into the log entry. You can jump from a single log line to the full trace it belongs to.

And here is the best part for existing .NET codebases: if you already use Microsoft.Extensions.Logging (ILogger), you do not need to change any of your existing log calls. Add the OTel logging exporter once, and all your log calls automatically carry trace context from that point forward.

What is an Exporter? 🔗

An exporter is the component that takes the telemetry data your application produces and ships it somewhere useful.

Think of it as a courier service. Your application boxes up the data - spans, metrics, log entries. The exporter is the courier that picks up those boxes and delivers them to wherever you want: Jaeger running on your laptop, a managed Datadog account, Azure Monitor, whatever fits your setup.

Because OTel separates the producing step from the shipping step, you can swap exporters without touching your instrumentation code. This is the whole point of vendor neutrality:

Console exporter - prints telemetry to stdout. Great for local development: you see spans appear in your terminal as requests come in. Zero infrastructure needed.
OTLP exporter (OpenTelemetry Protocol) - the standard wire format. Works with any OTLP-compatible backend (Jaeger, Grafana, Datadog, Honeycomb, Azure Monitor, and more). This is the one you'll use in real environments.
In-memory exporter - stores telemetry in memory. Mostly used in tests to assert that specific spans or metrics were recorded.

Switching from Jaeger to Datadog? You change the exporter configuration - one or two lines in Program.cs. The rest of your instrumentation code stays identical.

Busting the Myths 🔗

"OpenTelemetry replaces Jaeger / Datadog / Prometheus" No. OTel is the instrumentation and wire format layer. Jaeger, Datadog, and Prometheus are the storage, query, and visualization layer. They complement each other. OTel means you are not locked into any single backend.

"I will have to rewrite all my logging code" No. OTel integrates with Microsoft.Extensions.Logging. Your existing ILogger calls get trace context automatically once you add the OTel logging exporter. You do not touch the call sites.

"Tracing is only useful for microservices" Monoliths benefit too - sometimes more immediately. Slow database queries, external API latency, CPU-heavy code paths - traces expose all of this in a single-process application. If you have a database and an HttpClient, tracing is already useful.

"The performance overhead is not worth it" OTel sampling lets you record 1% of traces in production with near-zero overhead. You configure the sampling ratio. Use 100% in development. The SDK is designed to be a no-op when no exporter is attached.

"I need a paid service" Jaeger is free and open source. One Docker command and it is running. Prometheus is free. The OTel Collector is free. You only pay for a managed service if you decide you no longer want to run the infrastructure yourself - and that is a problem for later.

What's Next 🔗

Part 2 picks up from here with the hands-on side: wiring up OpenTelemetry in an ASP.NET Core application from scratch, running Jaeger locally in one Docker command, and adding custom spans and metrics that reflect your own business domain. If the concepts clicked here, the code in Part 2 will feel obvious.

Have you started thinking about observability for your .NET services? Drop a comment or reach me on LinkedIn or X - I'd love to hear where you are in the journey.

For more .NET deep-dives on ASP.NET Core, distributed systems, and architecture, check out the rest of the posts on irina.codes.

Api Versioning - A deep dive

2025-11-25T00:00:00Z

This article first appeared on systemdesign.one Newsletter.

Building Application Programming Interfaces ( APIs) is easy. Keeping them stable and predictable as the system evolves over time - that’s the real challenge.

API consumers depend on API contracts^1, and even the slightest change can break dozens of integrations. Rename a field, change a response format, change an endpoint entirely, and suddenly someone’s production system might stop working correctly. Systems grow, business requirements change all the time, and security or regulatory updates force adjustments that need to be communicated clearly.

That’s where versioning comes in. Versioning provides a structured approach to evolving APIs without leaving our API consumers behind. It sets the guidelines for how changes are introduced, how extensive those changes are, and how consumers can transition to new versions at their own pace.

But here’s the catch - just adding a version number in the URL doesn’t automatically prevent all the problems that might appear.

I’ve personally seen numerous APIs across different domains that expose a /v1/ in their URLs. Not that it’s a terrible idea, but years later, they are displaying the same version even though the API has changed a lot.

I find it hard to believe that nothing has changed in an API contract since they were first created. We often add new data, change property names, modify their types, remove fields, and so on. If so, why add a version at all?

The truth is, many APIs end up with “v1” in the URL forever because the same organization or teams control the consumer apps**.**

When the API owners and the API consumers are developed by different teams working at the same company, version upgrades are “just” code changes. Teams can synchronize deployments, push breaking changes, and update consumers without much risk of breaking changes.

However, the scenario changes completely when the API is exposed publicly, and you don’t own and control the consumers. Suddenly, you cannot just break compatibility.

You may be constrained by:

SLAs (Service Level Agreements)
Legal contracts
Third-party dependencies

…all of which force you to design carefully and communicate transparently.

You don’t want to spend nights answering angry support calls because someone’s app broke after you changed an endpoint. That pressure alone is often enough to influence how you version.

API as a Contract 🔗

It’s helpful to think about APIs as contracts. The contract describes the shape of the data, the form of the endpoints, and the behavior of the API. The client and the provider both agree to this contract.

However, contracts aren’t fixed forever - they evolve. A new field is added, a bug is fixed, or sometimes, a breaking change sneaks in. Versioning is our way of saying:

“Here’s the old contract — still valid.”
“Here’s the new one — with improvements.

The idea of a ‘contract’ helps both parties—the consumer and the API—understand each other. This way, they can communicate effectively.

When an API evolves, we usually have three paths forward:

Release a new version in a new location.

This means creating something like /api/v2/orders while keeping /api/v1/orders around. Current users can keep using the old version as is. They will switch only when they want the new features. This approach is safe and straightforward for clients, but it creates a lot of work for API owners. They now need to maintain several versions at the same time. This means fixing bugs, applying security updates, or implementing features for all supported versions. Over time, this can get very expensive and slow down future improvements.

Release a backward-compatible version

In this approach, the API changes in a way that doesn’t break existing clients. Typically, this means additive changes, such as new fields in a response, new optional parameters, or new endpoints. Consumers don’t need to update anything, since everything they used before still works the same way. The rules are tight. Even a tiny change, such as changing givenName to firstName, can cause compatibility issues. This happens because current clients might rely on the original name. This strategy works well for gradual growth but can be limiting when bigger design shifts are needed.

Break compatibility entirely

In this scenario, the API makes changes that require and force every client to upgrade.

At first glance, this sounds like the worst option—and often it is, because it forces all consumers to adapt quickly. But sometimes it’s unavoidable. For example, new rules might need a different data model. A serious security flaw could require significant changes. Also, the original API design may have issues that can't be fixed easily.

In reality, we need a mix of all three, depending on the type and impact of changes. And that’s where rules and versioning strategies come in.

Additive vs. Explicit Versioning

When you make additive changes only, your API evolves without incrementing its version. You add new fields, parameters, or endpoints, but never remove or rename anything. Additive changes are easy for consumers. They don’t have to change their integrations—but they force API designers to carry legacy choices forever.

By contrast, explicit versioning acknowledges when a change breaks compatibility. You create a new version using a URL, header, or parameter. This gives clients a clear boundary. They can see old behavior in one version and new behavior in another. Explicit versioning may require more maintenance, but it allows for bigger, cleaner design changes when needed.

Aspect	Additive Versioning	Explicit Versioning
What it is	Evolve the API only by adding fields, parameters, or endpoints	Introduce a new API version when breaking changes are needed
Backward compatibility	Fully preserved (no removals or renames)	Not preserved between versions
Impact on consumers	Very low — integrations continue to work without changes	Consumers must choose and migrate to the new version
Design flexibility	Limited — must keep all legacy choices forever	High — allows major redesigns or cleanup
Maintenance overhead	Lower initially, but grows with legacy baggage	Higher — must maintain multiple API versions
Ideal for	Stable APIs with infrequent changes	APIs that evolve rapidly or require periodic breaking improvements
Version indicators	None (single evolving API)	URL path (`/v2`), header, or query parameter

Types of API Versioning 🔗

Let’s walk through the different approaches to versioning an API, their benefits, and their drawbacks.

1. Path-Based Versioning 🔗

This is the most common approach:

https://coolapi.com/api/v1/orders

Path-based versioning solves the problem of clarity and visibility. Both developers and clients can easily identify which version they are using because it is visible upfront, in the path. This makes it easier for new consumers to follow documentation and quicker for developers to configure routing logic.

However, this clarity comes at the cost of stability. URIs change with every major version, which means clients may break unless the provider maintains multiple versions at the same time. For API owners, that means patching, monitoring, and duplicating logic across /v1, /v2, and beyond.

Pros:

Easy to see which version you’re using.
Simple to implement and route.

Cons:

Pollutes URLs with version info.
Every new version means new endpoints, potentially breaking existing clients.
Maintaining multiple versions creates redundancy and overhead.

It seems easy enough, but here’s the challenge:

Roy Fielding, the inventor of REST, reminded us that REST should imply evolvability,

If we correlate that with what Tim Berners-Lee said in 1998, that” Cool URIs don’t change,” we might have no reason to version in the URL. Not in the path anyway.

Let’s take a step back for a moment. A REST API is designed to work with representations of resources. For example, imagine your system has a domain with entities such as Orders or Cookies. You will have endpoints that manage them, allowing you to add, delete, or edit these items as needed. Once the API evolves, the new version of the API will change how the resource is represented. It can have new fields, or the structure may be slightly different, but the core concept will be the same. An Order will be an Order object, whether you’re looking at version 1 or version n of the API. It doesn’t turn into a Cookie object because you moved from v1 to v2.

Best practice: If you adopt path-based versioning, always keep older versions alive for a transition period. Announce clear deprecation timelines and provide migration guides. Use shared libraries for common logic so that bug fixes don’t need to be copied everywhere.

HTTP itself provides mechanisms for communicating versioning and deprecation. Two of the most useful are the Sunset header and 3xx redirects:

**Sunset Header (RFC 8594): lets an API signal when a version will no longer be available.**

Sunset: Wed, 01 Jul 2026 00:00:00 GMT

This communicates to consumers that the current version is scheduled to be retired on July 1, 2026. Combined with other headers like Deprecation: true, it gives clients time to plan migration instead of being caught off guard.

3xx Redirects Redirects are another simple way to guide clients from one version to another. For example, you can respond to a request for /api/v1/orders with a 301 Status code and a Location header that specifies where the resource can be found.

301 Moved Permanently
Location: /api/v2/orders

This helps consumers who aren’t ready to update their code right away. It also guides them toward the newer version. Redirects work very well when endpoints haven’t changed much—otherwise, clients may still need code changes.

Query Parameter Versioning 🔗

Instead of including the version in the path, the base URL is kept stable and the version is included as a parameter:

https://coolapi.com/api/orders?api-version=1.2.3

****This approach solves the problem of flexibility at the resource level. Developers can version specific endpoints or even individual resources without changing the overall API structure. Clients don’t need to update/store base URLs, and multiple versions can coexist on the same path.

Routers typically rely on paths, not query strings, so you’ll need custom logic in your gateway or application to handle version dispatch. Documentation must also be precise; otherwise, developers may forget to include the query parameter and end up confused.

Another important consideration is caching. To prevent serving the wrong version, ensure that CDNs and proxies cache ?version=1 and ?version=2 separately. This is because many treat query strings as part of the cache key. This also brings risks. Caches might not normalize parameters the same way, like ?version=2 and ?version=02. This can lead to cache pollution and lower hit rates. In poorly set up systems, some intermediaries might ignore query parameters. This can lead to clients getting the wrong version of a response.

Pros:

URL remains stable.
Versioning can be granular, down to a single resource.

Cons:

Routing becomes more complex (logic shifts to the handler).
Documentation and discoverability are trickier.
Caching can cause issues (pollution, misconfiguration, or wrong cache hits).
It can get messy when multiple parameters pile up.

Best practice: If you choose query parameters, configure your CDN or cache always to include them in the cache key. Document the parameter in each example call. Also, check its presence on the server side. This way, clients get clear error messages instead of silent issues. Normalize query strings where possible to avoid duplicate cache entries.

This works well when you want resource-level control, but it can complicate your codebase and caching strategy.

Message Payload Versioning 🔗

Here, the version is part of the request or response body itself:

{
  "version": "v1",
  "data": {
    "id": 123,
    "status": "shipped"
  }
}

Payload versioning facilitates the management of long-lived data in asynchronous systems. In event-driven or queue-based architectures, payloads can be stored for later replay. Including the version in the message allows consumers to know which schema to use, even after a long time.

However, this approach mixes concerns. Versioning is now part of business data. Each consumer must manage multiple schemas. For REST APIs with short request/response lifecycles, this adds extra complexity.

Best practice: Use payload versioning only for asynchronous or event-driven systems. Treat messages as fixed facts and create schema registries. This helps consumers safely deserialize old formats. Don't use this for standard REST APIs unless you need messages that last beyond your endpoints.

Header-Based Versioning 🔗

Here, the URL stays clean, and the version is passed in the request headers:

GET /api/orders
api-version: 2

Another approach is to version APIs through the Accept header. Instead of changing the URL or adding query parameters, the client specifies the resource version by requesting a specific media type. This is known as Media Type Versioning. For example, the client might use an Accept header value. The API will then respond with the resource formatted according to version 2 of the contract.

Accept: application/vnd.example+json;api-version=2
Accept: application/vnd.github.v2+json

Header-based versioning lets clients upgrade to new API versions at their own pace. This means they don’t have to rewrite or disrupt their integrations.

But there is a catch. Because version information is hidden in headers, it is less visible in logs or browser address bars. s. Debugging is more difficult if logging and tracing systems aren't set to record these headers. Proxies or middleware may even strip out unknown headers if not set up correctly.

Pros:

Keeps URIs stable and self-describing.
Aligns with HTTP semantics (metadata belongs in headers).
Works great with content negotiation.

Cons:

Version isn’t visible in the URL (harder for debugging, logging, and caching).
Some proxies or middlewares might strip or block custom headers.
Caching introduces some challenges because the version is shown in the Accept header. Caches (such as CDNs, reverse proxies, and browsers) require the correct setup to use this header when storing and delivering responses.

To solve this, add a Vary: Accept header. This tells caches that different Accept values lead to different responses. As a best practice, we should always include a Vary header in our responses (e.g., Vary: api-version or Vary: Accept) to prevent caches from mixing responses across different versions.

Adopting this option may seem complex, but it’s the cleanest and most sustainable choice long-term. Header-based versioning keeps your URLs stable. For example, the/orders endpoint will always point to the same resource, no matter the version. Instead of using different endpoints like /v1/orders or /v2/orders, versioning becomes part of the resource's representation. This fits well with HTTP and REST design principles.

This method also helps your API adapt to future changes. You can update representations without breaking links. It maintains consistency across endpoints and uses HTTP's content negotiation tools, such as Accept and Content-Type. This reduces fragmentation, keeps your API smaller, and offers a clearer contract for users.

The initial setup may require more effort. Teams need to configure caching properly with Vary: Accept and adjust their tools. However, the long-term benefits include a cleaner, more maintainable API that avoids piling up technical debt with each new version.

Now that we've covered versioning types, let's explore our options for versioning parameter format.

Versioning formats 🔗

1. Semantic Versioning(SemVer) 🔗

Semantic Versioning (SemVer) is a system that uses the format MAJOR.MINOR.PATCH. This helps illustrate the changes included in a release.

MAJOR - Breaking changes (clients must actively migrate).
MINOR - Backward-compatible changes (new fields, endpoints).
PATCH - Bug fixes only.

Example: 2.4.1 → second major release, fourth minor, first patch.

This gives consumers expectations: a jump from 1.9 to 2.0 is a big deal, but a rise from 2.4 to 2.5 should be considered safe.

2. Calendar Versioning(CalVer ) 🔗

CalVer is a versioning convention that uses dates instead of semantic numbers. Sometimes it is based on your project's release calendar.

Example: Ubuntu 24.04 - released in April 2024 (YY.MM format). Python 3.12.20231001 - could mean a release from October 1st, 2023 (YYYYMMDD format).

The version shows when the software was released. This helps us track freshness more easily than compatibility.

3. Hash Versioning(HashVer) 🔗

Hash versioning is a versioning scheme that uses hashes (like Git commit IDs) instead of numbers or dates. It allows us to reference a point in time for our software, hardware, or anything in between. Example: v-237a2b4f -could be the shortened Git commit hash where the build was cut.

The challenge with versioning is conveying a potentially large set of API changes into a single version label.

Real-World Case Study: Stripe 🔗

It’s one thing to talk theory, but let’s look at how a company like Stripe is designing its API. Stripe uses a header-based versioning approach: clients send a Stripe-Version header to indicate which API version they want. When a new user first makes a request, Stripe “pins” that account to the latest available version at that time. All future API calls from that account use that version by default unless the client overrides it.

Stripe-Version: 2023-10-16

Stripe also releases rolling versions^2, named by date, with most releases being backward-compatible. Only certain “major” or “release train” versions introduce breaking changes. Versions are named with dates (e.g. 2025-08-27.basil) rather than simple numeric “v1, v2” semantics

Why Stripe chose this approach — strengths & trade-offs

Strengths/rationale:

Stability for clients

Pinning an account to a version helps Stripe keep existing integrations safe during updates. Clients can upgrade when convenient. Stripe+1
Controlled breaking changes

Most changes are backward-compatible; breaking changes are introduced only at specific release points. This smooths the migration path. Stripe Docs+2Stripe Docs+2
Flexible overrides & experimentation

Clients can set the Stripe-Version header for each request. This allows them to test new versions without a full migration. Stripe+2Stripe Docs+2
Decouples API routing from versioning

Since the version is in the header, the URL doesn’t need to change. The path stays clean and meaningful.

In other words, Stripe turned versioning into a safe, consumer-driven choice. You decide when to upgrade, not Stripe. This aligns perfectly with the principle: don’t break your consumers without their consent.

Real-World Study case: GitHub 🔗

Another interesting case is GitHub’s REST API. GitHub uses header-based versioning with calendar-date identifiers. The base URL remains fixed: https://api.github.com/. Clients specify the version they want via the custom header:

X-GitHub-Api-Version: 2022-11-28

Notice that there is no /v1/, /v2/, etc. included in the path.
If no version header is provided, GitHub defaults to the latest stable version.
Each version is supported for at least 24 months, which means developers have a guaranteed migration window.
Breaking changes, like removing a field or changing behavior, trigger a new version. Non-breaking, additive changes roll out to all active versions.

Why this works well for them

Stable URLs : The resource path (/users/{username}, /repos/{owner}/{repo}) never changes. Versioning lives in headers, which keeps URIs clean and consistent with Tim Berners-Lee’s principle that “Cool URIs don’t change.”
Clear upgrade path: GitHub offers 24 months of support for each version. This helps ease the burden on large integrations. Teams can plan migrations with confidence, rather than scrambling every time a new release is introduced.
Clear boundary for breaking changes: Small, additive improvements don’t require a new version. This avoids “version churn,” where every little change creates another version to manage. At the same time, bigger shifts have a well-defined process.

GitHub’s approach highlights another philosophy: instead of thinking in v1/v2 jumps, think of your API as incremental snapshots in time. Clients pin to a snapshot and move forward when ready.

When to Increase the Version? 🔗

There’s no strict rule for when to raise a version number. It depends on many factors. Consider the following guiding questions:

How many consumers do you have?
How sensitive are they to breaking changes?
Are you bound by SLAs or legal obligations?
Can you realistically maintain multiple active versions of your software?

Be pragmatic. Don’t bump the version with every deployment. Only bump when the contract changes in a meaningful way.

Tooling for Managing API Versioning 🔗

Versioning isn’t just a design choice—it also needs operational support. Fortunately, there are plenty of tools that can help automate and manage the complexity:

API Gateways 🔗

Gateways act as the traffic managers for your APIs. They sit in front of your services, receive incoming requests, and decide how to route them. This makes it much easier to run multiple API versions in parallel.

Examples:
- Kong API Gateway lets you deploy plugins for version routing, deprecations, and logging.
- Apigee – supports versioned API proxies and detailed analytics.
- AWS API Gateway – enables you to run different stages (like v1, v2) and control access with IAM policies.
- Azure API Management – has first-class support for multiple versions and revisions, with portal-based documentation for each.

Usage scenario: You can keep /v1/orders active while routing /v2/orders to a new backend service, then gradually phase out/v1 once consumers have migrated.

API Documentation Frameworks 🔗

Good versioning isn’t just about routing traffic - it’s also about communicating and making the changes visible to consumers. Documentation frameworks make sure developers know which version they’re using and what has changed.:

Examples:

OpenAPI / Swagger: you can publish multiple YAML/JSON specs (v1, v2, etc.), generate docs with Swagger UI, and even compare schemas between versions.
Postman lets you group API requests by version and share version-specific collections with consumers. Also, it simplifies API testing.
Redoc - renders OpenAPI specs beautifully, making it easy to maintain docs for multiple versions.

Example in practice: You might publish orders-v1.yaml and orders-v2.yaml side by side. Swagger UI then shows consumers exactly what fields changed between versions, instead of leaving them to guess.

Usage scenario: You might publish orders-v1.yaml and orders-v2.yaml side by side. Swagger UI then shows consumers exactly what fields changed between versions, instead of leaving them to guess.

Versioning Libraries 🔗

Depending on your ecosystem, you might find a library that handles the plumbing for different API versions. This means you won't need to reinvent the wheel. These can be useful. They cut down on boilerplate code and ensure consistent versioning across your endpoints.

Examples:

.NET API Versioning – a widely used library that lets you define versions via routes (/v1/orders), query strings (?api-version=1.0), or headers.
Spring Boot API Versioning Approaches – a guide showing how to implement versioning in Java/Spring apps (header-based, URI-based, or content negotiation).
Express.js Versioning Middleware – allows Node.js developers to map different versions of handlers to the same endpoint.

Usage scenario: In ASP.NET Core, you can decorate a controller with [ApiVersion("1.0")] and [ApiVersion("2.0")], then route clients to the right version based on the api-version header

Tools don’t replace a good versioning strategy, but they make the work manageable at scale. Gateways manage routing and deprecation. Documentation frameworks provide clarity for users. Libraries ensure code consistency. Tools like Postman and Swagger UI show what’s changed.

Takeaway: When to Use Which Strategy 🔗

There’s no single “best” way to version APIs. Each strategy exists because it solves a different problem. The key is matching the strategy to your context:

Path-based versioning is best when you control all the consumers. It’s easy to read, easy to route, and works fine for internal systems where you can update clients in lockstep.
Query parameter versioning makes sense if you want granularity at the resource level. Use it when you need flexible evolution but can tolerate a bit more routing complexity.
Header-based versioning is the safest choice when you have external or long-lived clients you don’t control. It keeps URLs stable and allows consumers to decide when to upgrade.
Payload versioning works well for asynchronous, event-driven systems. In these systems, messages might be stored or replayed even years later. It’s overkill for typical REST APIs but powerful in streaming or messaging contexts.

And when it comes to version labels:

Use SemVer if you want to communicate the impact (breaking vs, additive vs. bugfix).
Use CalVer if you want to communicate freshness (when it was released).
Use HashVer if you care about traceability (exactly which commit produced this build).

In the end, choose the versioning strategy that surprises your consumers the least. If you ensure their stability and make migration paths clear, they’ll trust your API. That trust is more valuable than any technical detail.

Footnotes

^1 - API Contract - the formal agreement that defines how clients interact with an API—covering its endpoints, methods, request and response formats, and error handling—and breaking it means existing integrations may fail.

rolling versions^2 -

Competing Consumers Pattern: The Underrated Key to handling more load

2025-03-25T00:00:00Z

As a software architect, I'm always looking for patterns that reduce complexity, improve throughput, and make systems more resilient. One of the most powerful — and often overlooked pattern in distributed systems is the Competing Consumers Pattern.

If you have a system that has the right prequisites, aka, uses queues, has async messaging or it is event-driven, this pattern deserves a spot in your architecture toolbox.

In this post, I’ll break down:

✅ What the Competing Consumers Pattern is

✅ When and why to use it

✅ Key benefits and trade-offs

🔍 What Is the Competing Consumers Pattern? 🔗

The Competing Consumers is a design pattern in asynchronous message-based systems where multiple consumers pull messages from the same message queue. Each message is being proccessed by only one consumer, and the consumers “compete” to process messages off the queue as they arrive.

This approach allows us to scale horizontally,without too much hassle, automatically balancing load across multiple worker instances.

Why Use the Competing Consumers Pattern? 🔗

Here are the core problems this pattern solves:

Handling Variable Workloads - Message queues act as a buffer between producers and consumers, leveling out the load. By increasing the number of consumers, you process more messages, without changing the producer logic.
Scalability - You can add or remove consumer instances to scale horizontally, when needed, based on traffic. This is great for cloud-native, serverless, or containerized environments.
Resilience - If one consumer crashes, others continue processing messages without interruption, giving you a bit of redundancy when it comes to processing messages.

How does it look in practice 🔗

Producers send messages sends messages to a queue.(e.g., an API or upstream service)
The queue (or broker) stores the messages until a consumer is ready to process them.
Multiple consumer instances pull/get messages from the same queue and process messages independently.
Each message is guaranteed to be processed by only one consumer, and as it is processed is not accessible by other consumers.

Trade-Offs and Design Considerations 🔗

Like any architectural pattern, Competing Consumers comes with its own set of challenges:

Message Ordering 🔗

When multiple consumers are involved, FIFO order is not guaranteed unless explicitly implemented (e.g., with message sessions in Azure or partition keys in Kafka).

🔁 Idempotency & isolated/independent message processing 🔗

Consumers should be idempotent—able to process the same message more than once without side effects. This is crucial when retries happen. Stricly speaking, in an asyncronous messaging world, you should always strive for that. Also, each message should be able to be processed independent of other messages. Just as we talk in REST API that requests/responses should be able to be processed in isolation. Same here. Consumers shouldn't need to have context about what messages have been processed before, or of what comes after.

Poison Messages 🔗

Some messages might always fail to process. Leverage dead-letter queues (DLQs) with a suitable error management strategy to isolate and analyze them quickly. On top of that, having an Error management platform might save you valuable time and aid in implementing recoverability.

📈 Observability 🔗

As observability should be a first-class citizen in any system, the Consumer throughput, queue length, and error management should be monitored. Having some metrics ensures that you can smartly auto-scale your consumers. For example, if you notice that messages are piling up in a queue, up to a threshold, without receiving errors. It might indicate that you need more 'workforce,' you could add a new consumer to the queue to help spread the load.

🧩 When Should You Use This Pattern? 🔗

The short answer an architect would give is: it depends. Of course, it depends on several factors:

your workload is bursty or unpredictable, or it is predictable. You will know you will have an event that will cause an increase in the processing need—for example, a Black Friday sale.
You have some long-running processing to do, and you need to process more. In this case, you could dynamically scale

Don’t use it when: 🔗

You require strict message ordering
Messages must be processed exactly once with no duplicates (hard guarantee)

💬 Final Thoughts 🔗

The Competing Consumers Pattern is a fantastic way to handle more load and temporarily scale parts of your system. It’s simple to implement and powerful in practice—especially in cloud-native architectures.

Whether you’re processing millions of messages daily or want more resilience by adding a bit of redundancy to your consumers, this pattern has your back.

MassTransit with Azure Service Bus - Error management

2025-02-13T00:00:00Z

When working with distributed messaging systems, failures are inevitable. Whether it's transient network issues, processing errors, or service unavailability, handling and addressing failures gracefully is crucial.

In this post we explore how with can deal with messages that can’t be processed by MassTransit endpoints and how to recover messages that end up in erorr quues or DLQs.

Handling failures in MassTransit 🔗

MassTransit allows us to configure different policies for handling transient failures:

Retries: Automatically retry a failing message with exponential backoff. Has some policies we can apply
Circuit Breakers: Prevent overwhelming a failing service with continuous retries.
Redelivery : Move a message to an error queue after exceeding retry attempts, for a much later redelivery

These mechanisms are the first step in ensuring resilience against transient failures and preventing message loss. However, they can’t guarantee that a message will be successfully processed before the retry attempt is exhausted.

If that happens, the messages are moved either an Error queue, or a Dead-Letter queue. That’s the last stop for them, they go dormant until we wake them up and reprocess them. MassTransit, by convention, will create <queuename>_error for any queue from where the message couldn't be processed sucessfully, unless explicitly told otherwise.

Recovering failed messages 🔗

All messages that end up in error queues should be considered valuable to the business. They can end up there for various reasons: the database is down, there is a network glitch, the consumer server is slow, etc. Let’s say that the consumer endpoint was down and is now up and running again, and we are ready to replay all the failed messages. From this point on, nothing could automagically start the processing flow from where it failed.

We would have to dig through the failed messages and restart the flow. If you have one or a few messages, the process can be painless enough, but what if you have hundreds? Or thousands? What then?

Luckily, the recoverability processes can be done with the help of Service Bus Explorer or by setting up a dedicated consumer.

Although this works like a charm, it has basic capabilities. It forces you to click through a not-so-simple interface endlessly and to think in engineering terms.

More than that, it is almost impossible if you want to give better visibility over the system to someone not involved in the development process or allow anyone to help correct the errors. Let’s face it: Azure Portal is not the friendliest place to be. I am sometimes scared not to click the wrong button.

With this aside, reprocessing a large number of messages from the dead-letter queue (DLQ) or an error queue can be challenging for anyone, especially when there is no way to group them efficiently. Each message must be manually retrieved and inspected without any categorization or sorting capabilities.

This lack of features increases operational overhead and slows recovery efforts, making it difficult to restore normal processing quickly. We do want to visibility and avoid tedious work right, right?

How about if I told you we have a platform that can be easily integrated with MassTransit endpoints that use Azure Service Bus, making message reprocessing effortless?

Recovering failed messages the easy way 🔗

MassTransit Error Management is a platform that can be easily set up, and removed, runs in Docker, and knows how to talk error queues, and DQLs.

The Particular team set up an interesting demo, very well documented that works with Azure Service Bus and RabbitMQ. Feeel free to have a look.

Now, let’s explore the platform named ServicePulse. This integrates with MassTrasit endpoints and allows you to specify which queues you want to monitor. As soon as it detects failed messages in those queues, it will transport these messages in this centralized dashboard where you can easily group, sort, retry, edit, and even delete the failed messages.

So let's see what it brings to the table:

Visualizing all messages 🔗

The platform exposes different views for failed messages: Groups, All, Deleted, and All Deleted, all in a very friendly and interface.

It gives you an birds-eye view of the:

Type of the message that failed.
Time of failing
Endpoint where the message processing failed
Machine that processed the message
The exception of the failing message

From here you can select the messages that you want, and you can retry them or delete them.

Grouping messages and sorting 🔗

Grouping and sorting is an importan feature as it can really help you save time. When you have many error message types and you want to skim trough them fast. If you know that a Shipping consumer failed to process the messages, then you can retry the entire group. In the image below you will see 3 distinct groups.

Visualizing and editing individual messages 🔗

Each message can be viewed independently too. We can see the Stacktrace, Headers and the Body of the message with all the details.

The message can be retried as it is, or we can Edit & Retry to apply changes to the body or header.

Retrying groups of messages 🔗

Retrying groups of messages when you don't want to edit anything is very straightforward. Below you can see two groups of messages:

the first one was already retried, and had 2 messages
the second one is queued for retrying, and it has 3 messages

Deleting the failed messages 🔗

Although all messages are valuable, since they contain business data, there might be cases when you would want to discard some of the messages.

If anyone deletes a message by mistake, the message is gone forever, without any backup. You would have not way of recovering that.

The Particular platform keeps the deleted messages for 15 days, just in case you change your mind and you want to restore them, or in case some were deleted by mistake.

We like it or not, in distributed system errors are inevitable and we shouldn't be scared of those. What we should do instead is to try and adopt the strategy and tools to allow us to move fast enough and recover from them.

I've seen teams struggling to recover messages because they didn't have the right permissions or weren't used to the Azure Portal.

Sometimes not using the right tools can lead to delays, inconsistencies, and additional complexity in handling error messages effectively.

Summary 🔗

Recoverability is a quality attribute that is not easy to obtain and often overlooked, but the MassTransit erorr manangement platform helps with this.

Instead of manually handling each message one by one, this solution provides intelligent grouping, batch processing significantly reducing operational overhead. With built-in visibility, filtering, and retry controls, you can quickly identify failed messages, apply corrective actions, and ensure seamless recovery— all without disrupting your existing system. Plus, is user-friendly!

Getting started: Messaging in .NET with MassTransit

2024-07-10T00:00:00Z

I'm thrilled to announce that my course "From zero to hero messaging in .NET with MassTransit" was released on Dometrain

I this course for you? 🔗

In this course, we’ll explore the ins and outs of asynchronous communication patterns, with a focus on MassTransit —a powerful message broker for .NET applications. Have you ever dreamt of building applications that can handle complex workloads with ease?

Well, buckle up, because asynchronous messaging with MassTransit is about to become your new best friend!

This course is designed for three types of heroes:

C# Software Developers: If you're already slinging code in C#, you've got a great foundation for diving into asynchronous messaging.
C# Architects: Looking to elevate your design skills and craft scalable, performant applications? This course will equip you with the knowledge to do just that.
MassTransit and asyncronous messaging Newbies: Maybe you've heard the buzz around MassTransit, but aren't sure where to start. Fear not, curious minds! This course will guide you every step of the way.

As a hands-on software architect, I witnessed first-hand how people in different teams struggle to shift their mind-set to adopt an asyncronous messaging approach.

At first, is a bit unusual to think in terms of messages, react to those messages in different components, and not have status codes to guide you.

I know it is hard too, but sometimes we have to unlearn what we know from building traditional APIs in order to design better ones. Reality tells us that the APIs that respond to ever increasing throughput needs, are resilient and more robust.

In the course, we will start by learning the basic concepts about asynchronous messaging, how it is different than REST and then progress towards concepts like Pub/sub, request/reply, different architecture types, pipes & filters, Pull& Push consumption models and many more.

And if you ask me, designing and building a good system sometimes reduces to applying well tried recipes, others were using before you, like Outbox Pattern and Saga Pattern.

You can see here the list of topics that are covered in the course. And of course, you will also get the source code as a resource for the course.

Outcome 🔗

By the end of this course you will be able to apply asynchronous messaging concepts in enterprise applications. You will be able to extrapolate the examples and use them in your scenarios.

So, if you're ready to unlock the power of asynchronous messaging and build next-level applications with MassTransit, then check it out and let's get started!

PS: Don’t forget to connect , and let me know what you think about the course.

Enjoy!

You can click here to checkout the course directly

Adapter design pattern

2024-02-24T00:00:00Z

Adapter design pattern 🔗

Name: Adapter

Type: Structural

Intent: 🔗

“Convert the interface of a class into another interface the client expects. Adapter lets classes work together that couldn’t otherwise because of incompatible interfaces.”

In other words, this pattern makes incompatible interfaces compatible.

When to use: 🔗

Sometimes, objects just don’t fit together as they should. Either the object is too complex to work with or their interfaces are incompatible. The adapter design pattern lets you adapt what an object or class has to offer, by converting the interface of a class into another one. There are some common use cases like: integrating external libraries with different interfaces, working with legacy systems or adapting data formats

Real-life analogy 🔗

One of the real-life encounters with an Adapter is with headphone jacks. These jacks aren’t universal, and we won’t find the same jacks in all phone models. In these cases we might need adapters to convert a 3.5mm jack to a USB-C or Lightning connector, allowing headphones to work with different devices.

In all of these cases, the adapter is a middleman that translates the signals or data from one system to another, making it possible to connect incompatible objects or interfaces.

Imagine two people who speak different languages trying to have a conversation. The Adapter acts like a helpful translator, listening to one person (object 1) in their language and then seamlessly converting their message into terms understandable by the other person (object 2). This allows them to communicate effectively despite their initial incompatibility.

Structure 🔗

For the Adapter design pattern, we have three main entities involved.

The interfaces are the abstractions that need to be made compatible.
The Adaptee - is the original class that needs to be adapted. In our case, the iPhone needs to be charged with a different charger
The Adapter - LightningToTypeCAdapter is the class that knows how to talk with both the client and the Adaptee(i.e knows how to adapt a Lightning port to type C one)

You can see in the diagram below the interaction between classes.

Implementation 🔗

 public interface ITypeCPort
 {
     void Recharge();
     void UseTypeC();
 }

 public interface ILightningPort
 {
     void Recharge();
     void UseLightning();
 }

Then we have an IPhone that implements the ILightningPort.

 public class IOSPhone : ILightningPort
    {
        private bool isConnected = false;

        public void UseLightning()
        {
            isConnected = true;
            Console.WriteLine("Lightning connection established");
        }


        public void Recharge()
        {
            if (isConnected)
            {
                Console.WriteLine("Recharging iPhone...");
            }
            else
            {
                Console.WriteLine("Please connect Lightning first");
            }
        }
    }

Then we need to have an adapter.

 public class LightningToTypeCAdapter : ITypeCPort
 {
     private ILightningPort lightningPhone;

     public LightningToTypeCAdapter(ILightningPort lightningPhone)
     {
         this.lightningPhone = lightningPhone;
     }

     public void UseTypeC()
     {
         Console.WriteLine("Adapter converts Type-C to Lightning");
         lightningPhone.UseLightning();
     }

     public void Recharge()
     {
         lightningPhone.Recharge();
     }
 }

From the client's perspective, now we can have an iPhone, use an adapter and recharge our phone.


IOSPhone myIPhone = new IOSPhone();
LightningToTypeCAdapter typeCAdapter = new LightningToTypeCAdapter(myIPhone);

Console.WriteLine("Attempting to recharge iPhone with Type-C via adapter:");
typeCAdapter.UseTypeC();
typeCAdapter.Recharge();

Structurally speaking, the Adapter design pattern is very similar to the Proxy design pattern. But unlike Proxy, The Adapter pattern is visible to the client, and the client knows that it interacts with an adapter.

Pros & Cons 🔗

Pro 🔗

enables integration of systems with incompatible interfaces with the rest of the codebase
Code reuse - can reuse existing functionality that is not compatible with the desired interfaces by using adapters
enhances flexibility and maintainability by decoupling the client code from specific implementations of the Adaptees
promotes ** loose coupling **
Extensibility : adapters can be easily extended to accommodate new interfaces without modifying the adaptee code
Reusability: Adapters can be reused with different Adaptees
Open/ Closed principle - we can introduce new adapter types without modifying existing code
the Adapter pattern hides the implementation details of the Adaptee, shielding client code from the complexities of its internal workings. This promotes abstraction and makes the code more maintainable and testable.

cons: 🔗

can introduce complexity in the system due to adapter classes, and the code can be harder to understand
Requires thoughtful design considerations to ensure that adapters are appropriately implemented and don't introduce unintended consequences.
Requires more testing

Summary 🔗

Proxy design pattern

2024-02-13T00:00:00Z

Proxy design pattern 🔗

Name: Proxy Type: Structural

Intent: 🔗

The Proxy design pattern is a structural pattern that provides an in-between, or placeholder for another object. They are closely related in structure, to Adapters and Decorators but they have different purposes.

When to use 🔗

The Proxy design pattern can be used in a variety of scenarios, but its goal is generally to preserve exactly (or as closely as possible) the API that is being used while offering certain internal enhancements.

It's useful when we want to add a layer of control over the interaction with an object. In the context of C#, implementing the Proxy pattern involves creating a proxy class that wraps an object and controls access to it.

Real-life analogy: 🔗

Imagine you are at a restaurant that has a limited number of tables. The restaurant has a hostess who stands at the door and checks if there is a table available before seating a customer. The hostess acts as a proxy for the tables. She controls access to the tables and chairs and ensures that the tables are distributed as best as possible.

Another example we often encounter in real life is when we order coffee. When we want to order a coffee, we don't go directly to the barista behind the counter or make it ourselves. Instead, we place the order with a person, who then relays the order to the barista. The person taking our order acts as a proxy for us, handling the communication and coordination between us and the barista.

Structure: 🔗

For the proxy design pattern, we have three main entities involved.

One is the abstraction which is usually an interface that defines the operations
The real Subject - a class that implements the interface and usually has more operations than is specified there
The Proxy acts as an intermediary between the Client and the Real Subject. This too implements the interface and has-a Real Subject instance. It is the common ground between the Client(consumer) and the Subject, providing an indirection layer.
The client is the one interacting with the Proxy

You can see in the diagram below the interaction between classes.

Implementation 🔗

For our example implementation we have the following components:

The IOrderService interface represents the service interface for placing food orders.
The RestaurantKitchen class is the real subject that prepares the food. This is the actual code that we want to interact with.
The Waiter class acts as a proxy for the RestaurantKitchen. When a client wants to place an order, the waiter can perform various tasks (like confirming the order, checking special requests, etc.) before delegating the actual food preparation to the RestaurantKitchen.
The client interacts with the IOrderService interface and uses the Waiter to place orders. The client is unaware of the direct interaction with the RestaurantKitchen which illustrates the encapsulation provided by the Proxy pattern.

This design allows for additional logic and features to be implemented in the Waiter without modifying the underlying RestaurantKitchen or the client's code.

// Service Interface
public interface IOrderService
{
    void PlaceOrder(string dish);
}

// Real Subject
public class RestaurantKitchen : IOrderService
{
    public void PlaceOrder(string dish)
    {
        Console.WriteLine($"Cooking {dish} in the kitchen.");
    }
}

  public class Waiter : IOrderService
  {
      private RestaurantKitchen _kitchen;

      public Waiter(RestaurantKitchen kitchen)
      {
          _kitchen = kitchen;
      }

      public void PlaceOrder(string dish)
      {
          Console.WriteLine($"Waiter is taking order for {dish}.");
          // Additional checks or preparations can be done here.
          _kitchen.PlaceOrder(dish);
      }
  }

Pros & Cons 🔗

Pro 🔗

Control Access: The proxy can control access to the real subject(RestaurantKitchen), which is useful for lazy initialization, permissions, etc.
Additional Functionality: You can add additional functionality (e.g., caching, logging, monitoring) before/after the request to the real subject.
Open/Closed Principle: You can introduce new proxies without changing the subject or client

CONS: 🔗

Code Complexity: Code may become complicated, if both the real subject and proxy implement the same interface.
Response Time: The proxy can add a delay to the response time due to additional processing.
adding a layer of indirection

The Proxy Design Pattern stands out as it does not conform to a single, uniform structure. There is a wide variety of proxy types that serve distinct functions. The choice of which one to implement depends on the specific requirements of the software design problem at hand. Below there are just a few of them:

Proxy types: 🔗

Virtual Proxy: This type of proxy creates expensive objects on demand. The proxy contains a placeholder for an object that is extremely resource-intensive to create. The actual object is only created when its functionality is absolutely needed. This is useful in scenarios like lazy initialization of a large image or a file.
Remote Proxy: This proxy provides a local representative for an object that resides in a different address space (like another computer or server). It's used in distributed systems to hide the details of remote interaction. The proxy takes care of the details of working with remote methods, such as handling network communication and marshaling.
Protective Proxy: This proxy controls access to a sensitive master object. It's used to manage the different access rights of clients and to protect the target object from unauthorized access. For example, it might check if a client has the necessary permissions to perform an action.
Smart Proxy: A smart proxy adds extra layers of functionality when an object is accessed. This can include additional steps when an object is accessed, such as reference counting, logging, or locking to manage concurrent access to an object. It can also perform tasks that are needed for housekeeping purposes, like freeing resources or initializing objects upon access.
Caching Proxy: This proxy can store recent or frequent requests and provide cached responses to reduce the operation's time or complexity. It's commonly used in systems where fetching or calculating the original data is very resource-intensive, like in web content delivery networks.

Each of these proxy types serves a different purpose, and the choice of which one to implement depends on the specific requirements of the software design problem at hand.

Summary 🔗

In essence, the Proxy design pattern is a powerful tool that can take many forms. It doesn’t try to expand the public API surface of an object by adding new members but it can control access and add supplementary behavior to objects without changing the object's code or the client's code.

P.S. Want the source code or level up your coding? Consider joining my monthly newsletter. Sign up here!

Decorator design pattern

2024-02-05T00:00:00Z

Decorator design pattern 🔗

Name: Decorator

Alternative name: Wrapper

Type: Structural

Intent: 🔗

Attach additional responsibilities to an object dynamically. Decorators provide a flexible alternative to subclassing for extending functionality.

When to use: 🔗

The decorator pattern is particularly useful when we want to provide a myriad of customization options for a basic/base object because it allows us to add new functionalities to an object without altering its internal structure.

Real-life analogy: 🔗

For example, when ordering a coffee, we might like that coffee with sugar, milk, or soy milk and we might add some cinnamon or whipped cream. Or, we might want some nice sprinkles on top. The sky is the limit here.

Another example is cake 🎂. We all love cakes,(I definitely do) and the variations are endless. Any cake can be customized in numerous ways to create a unique and memorable treat.

IT can start from a base cake and take different forms and shapes depending on who orders or eats it. Variations encompass diverse cake bases, tantalizing flavors, fillings, enticing fruit layers, rich icings, and eye-catching decorations🧁.

Imagine how such a scenario would look in terms of code.

Usually, when it comes to altering an object's structure or behavior, inheritance might be the first thing that comes to mind, but it might not be the best thing. In this scenario, subclassing wouldn’t be a great idea at all. Moreover, in time, we would have so many classes and spaghetti code that it would become impossible to manage.

By using inheritance, it would mean changing an object with another one, and it would only allow us to have one single base class. Inheritance is static and we need a way to alter the object’s structure, dynamically, at runtime.

One way to overcome this static issue is to use Aggregation or Composition. (remember- there is also a design principle that tells us to favor composition over inheritance.!!).

it is better to compose objects to achieve polymorphic behavior and code reuse rather than inheriting from a base class.

These two concepts sit behind many design patterns, and this happens here too. So, let’s see how to model such a thing in C#.

Structure: 🔗

Implementation 🔗

First, let’s have a look at the components needed:

ICake - the abstraction common
BaseCake class - that will implement the interface and act as our base object to which we will add enhancements to
BaseCakeDecorator - an abstract class that contains the object that we wrap as a field. The field’s type should be declared as the component interface so it can contain both concrete components and decorators. The base decorator delegates all operations to the wrapped object.
ChocolateFilling - is a concrete decorator (i.e. a concrete implementation of the BaseCakeDecorator) that we will use to wrap our BaseCake, to customize it as we want
Spinkles - it can be added as decoration too

public interface ICake
{
    string GetDescription();
    decimal GetCost();
}

 public class BasicCake : ICake
 {
     public string GetDescription()
     {
         return "Basic Cake";
     }

     public decimal GetCost()
     {
         return 10.0m;
     }
 }

/// Decorator abstract class
public abstract class BaseCakeDecorator : ICake
{
    protected ICake decoratedCake;

    public BaseCakeDecorator(ICake cake)
    {
        decoratedCake = cake;
    }

    public virtual string GetDescription()
    {
        return decoratedCake.GetDescription();
    }

    public virtual decimal GetCost()
    {
        return decoratedCake.GetCost();
    }
}


// Concrete decorator: ChocolateFilling

public class ChocolateFilling : BaseCakeDecorator
{
    public ChocolateFilling(ICake cake) : base(cake)
    {
    }

    public override string GetDescription()
    {
        return $"{base.GetDescription()} with Chocolate Filling";
    }

    public override decimal GetCost()
    {
        return base.GetCost() + 5.0m;
    }
}

// Concrete decorator: ChocolateFilling

 public class Sprinkles : BaseCakeDecorator
 {
     public Sprinkles(ICake cake) : base(cake)
     {
     }

     public override string GetDescription()
     {
         return $"{base.GetDescription()} with Sprinkles";
     }

     public override decimal GetCost()
     {
         return base.GetCost() + 2.0m;
     }
 }

Now we can create complex variations by using the concrete decorators that we have, starting with the base. Then, we can take the base and apply different decorators. The example below is exaggerated, but I hope it gives you an idea about how it can be used


ICake basic = new BasicCake();
ICake basicWithChoolateFilling = new ChocolateFilling(basicCake);
ICake basicWithChoolateFillingAndFruitFilling = new FruitFilling(basicWithChoolateFilling);
ICake basicWithChoolateFillingAndFruitFillingAndSprinkles = new Sprinkles(basicWithChoolateFillingAndFruitFilling);

Pros & Cons 🔗

Pro 🔗

We can give objects new responsibilities without making any code changes to the underlying classes.

Wearing clothes is an example of using decorators. If it is cold, we might layer ourselves with a few more clothes than in the summer. This is an example of using decorators at runtime. We are not born with clothes, and we don’t become different people just because we wear different clothes(if we were to use inheritance), we use clothes when we need them, as many as we need them.

Helps us 'achieve' Open/Closed principle The decorator has the same supertype as the object it decorates, we can pass around a decorated object in place of the original
encourages us to write code that adheres to the SOLID design principles.
gives us more flexibility than static inheritance
because decorators only rely on the interface of decorated objects (injected through the constructor of the decorator class), decorators can be unit tested independently.

CONS: 🔗

All methods specified in the interface must be implemented in the concrete decorators, and if we don’t add additional functionality, we must use those as pass-through -** Lots of little objects**. A design that uses the Decorator design pattern often results in systems composed of lots of little objects that all look alike. The objects differ only in the way they are interconnected, not in their class or the value of their variables. Although these systems are easy to customize by those who understand them, they can be hard to learn and debug
Decorators can be tested in isolation of decorated objects but subclasses cannot be tested in isolation of their parent.

Summary 🔗

The Decorator design pattern acts like a wrapper, giving us the ability to enhance base objects. This enhancement is dynamic, happening at run-time, without altering the base object’s structure. I can say that the decorator behaves very much like an extension method, that allows us to add extra functionality where we can’t or won’t change the base class. In essence, the decorator design pattern provides us a flexible mechanism to extend the functionality of existing objects, without changing their internal structure. It is like changing the case of your phone, not the internal structure of it

Hosting gRPC in Azure

2024-01-18T00:00:00Z

How to host a gRPC service in Azure? gRPC on Linux?

When it comes to hosting a gRPC service to Azure, things are pretty straightforward, but there are a few tips and tricks that we will cover.

If you have, like me, a not-so-complicated system, or you simply want to play around with the gRPC service deployed in the cloud, then this is for you.

Make sure you have an app Service plan ready and a Web App with Linux. Currently, only Linux is supported for gRPC.

So, first, a gRPC service is nothing more than a regular API with a few particularities, that need to be set in the Azure Web App prior to deployment:

uses HTTP/2
uses a binary serialization

How you get your code source in the Cloud it's up to you. You can publish directly from the IDE, or have a pipeline that runs when you push to GitHub. As long as you will be able to move your source code to the cloud, then you are all set.

Since we are dealing with a gRPC service, we need to ensure that we have HTTP version 2, and that the HTTP 2.0 Proxy is enabled, as shown in the picture below.

The next thing we will need to do is to add an application setting named HTTP20_ONLY_PORT with the value of 8585.

With these things done, we should be able to test our service, from our local machine, by instantiating a client. But if we want to use Postman, for example, is advisable to install Grpc.AspNetCore.Server.Reflection package and enable the middlewares.


builder.Services.AddGrpcReflection();
...

app.MapGrpcReflectionService();

Make sure the application is up and running, by accessing the URL provided in Azure: e.g: https://yourgrpcwebiste.azurewebsites.net/, and now you can use Postman for example to make requests.

In Postman, select the 'use server reflection` option to make sure the operations are discoverable. After that, we can make requests, just as we would do with a regular Web API.

The laws of software development

2023-12-14T00:00:00Z

Unlike legal statutes, software development 'laws' are not binding regulations or practices. These are rather distilled insights into the intricacies of software creation. These principles serve as valuable guides, steering developers away from common pitfalls and promoting effective practices.

We can look at these ‘laws’ as popular knowledge, that captures common observations and best practices. Many software development laws apply in different areas. Some apply to project management, some apply to software architecture, some to ways of working or organizations.

Below we will cover the most common ones.

Table of Contents 🔗

Pareto Principle (80-20 Rule) 🔗

Statement: 80% of the effects come from 20% of the causes

Source: This principle is named after Vilfredo Pareto, an Italian economist and sociologist who observed that 80% of the land in Italy was owned by 20% of the population.

Explanation: While not specific to software development, the Pareto Principle is often applied in various contexts, including software. The stated idea is that a significant portion of results or outcomes often come from a relatively small portion of inputs or factors. In our field, it might suggest that focusing on fixing the most critical 20% of software bugs can eliminate 80% of the issues.

Conway Law 🔗

Statement: Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization's communication structure.

Source: The source for Conway's law is an article written by Melvin Conway in 1968. It was later dubbed “Conway’s Law” by Fred Brooks in his hugely influential book The Mythical Man-Month

Explanation: The idea of this law is that consciously or not, organizations that have small distributed teams tend to develop systems that are modular and use service-based architectures. On the other hand, organizations that have large and colocated teams tend to develop monolith-like architectures. Conway's Law highlights the idea that communication and collaboration patterns within an organization have a direct impact on the architecture and design of the systems they create. It's a reminder that we should consider the organizational structure when we plan and design complex systems.

Understanding Conway's Law can be valuable for organizations looking to improve their software development processes. By aligning team structures and communication patterns with the desired system architecture, organizations can work more efficiently and produce systems that better meet their needs.

Postel's Law of Communication and Robustness 🔗

Statement: "Be conservative in what you send, liberal in what you accept.”

Source: It was coined by Jon Postel, a computer scientist who played a key role in the development of the early internet.

Explanation: It states that when a system sends data, it should send it in a well-defined manner and adhere strictly to the specifications and standards governing the communication protocol. On the receiving end, the system should be flexible in interpreting the received data. It should accept and interpret inputs even if they deviate from the standard too. This flexibility promotes interoperability and allows systems to work together effectively, even if they have minor differences. This law promotes preventing situations where strict adherence to standards might lead to communication failures, especially in a networked environment where different systems with different implementations need to interact.

Murphy's Law of Software Development 🔗

Statement: If anything can go wrong, it will, and often at the most inopportune moment.

Source: Everyone's heard of "Murphy's Law," right? The whole "if anything can go wrong, it will" thing. Well, it's named after an aerospace engineer named Edward Murphy Jr., who worked at Edwards Air Force Base in the 1940s. He was testing a braking system for a rocket sled when a cable snapped, sending the sled haywire and injuring the pilot. Murphy said something like "If there's any way for things to go wrong, they will." His buddy Capt. John Saintsbury shortened it to "Murphy's Law," and it's been a part of our vernacular ever since. It's a reminder that things don't always go according to plan, especially when you're dealing with complex machinery or high-stakes situations.

Explanation: This law highlights the inherent unpredictability of software development. It reminds us that even the most carefully planned and executed projects can encounter unexpected problems, and we can't prevent all of them.

Law of Demeter (Principle of Least Knowledge) 🔗

Statement: "Each unit should have only limited knowledge about other units: only units 'closely' related to the current unit." or "Only talk to your immediate friends."

Source: The Law of Demeter, also known as the Principle of Least Knowledge, originated from the work of Ian Holland in 1987 as presented in his paper titled "On the Criteria To Be Used in Decomposing Systems into Modules." Karl Lieberherr later coined the term "Law of Demeter" in homage to the Demeter project, initiated by Lieberherr and colleagues in the 1980s, which aimed to apply the principle to achieve more modular and maintainable software designs. Ian Holland formulated the principles, while the Demeter project significantly contributed to the principle's popularization and application within the software engineering community.

Explanation:

We can split this law into 3 parts:

Only talk to your immediate neighbors: An object should interact with its immediate neighbors and not with distant or unrelated objects. This means that an object should not have detailed knowledge about the inner workings or structures of other objects that are not directly related to its purpose. If we think about SRP, this makes total sense.
Don't talk to strangers: When an object needs something done, it should delegate the task to its immediate friends (i.e., the objects it holds references to), rather than reaching out to objects it doesn't know about.
Limit the interaction and knowledge hierarchy: An object should not expose its internal structure or the structure of objects it interacts with to the outside world. It should only reveal a minimal, well-defined interface. Focus on Encapsulation and prevent chattiness.

This law advocates that we should aim to reduce coupling between different parts of a system, making each component more independent and easier to maintain. In other words, it emphasizes the importance of minimizing dependencies and promoting modular, loosely coupled system designs in object-oriented programming.

Amdahl's Law 🔗

Statement: The law states that the maximum speedup achievable by a parallel program is limited by the fraction of the program that cannot be parallelized, known as the sequential fraction (S). The formula for Amdahl's Law is:

Speedup = 1 / (1 - S + S/P)

where P is the number of processors used.

Source: Amdahl's Law is a principle in computer architecture and parallel computing named after computer architect Gene Amdahl. Formulated in 1967, Amdahl's Law quantifies the potential speedup of a computation when parts of the computation are parallelized.

Explanation: Amdahl's Law can be applied to a wide variety of parallel computing applications like data processing, database systems and computing in general. But, no matter where we try to apply it, mathematically speaking we will never be able to parallelize a program 100% and there will always be a limit to the speedup. This limit is given by the small things that are sequential: input/output, control flow, memory management, etc. When it comes to optimizing, we should look out for these things. Simply put, Amdahl's Law says that only certain parts of a program can run faster on multiple computers. Focus on optimizing those parts to get the most speed from your parallel system.

Gall’s Law 🔗

Statement: "A complex system that works is invariably found to have evolved from a simple system that worked."

Source: The law was developed by American author John Gall in his 1977 book "Systemantics: How Systems Really Work and Why They Fail".

Explanation: Gall's Law highlights the importance of starting with a simple working system and gradually adding complexity as needed. This approach can help to reduce the risk of introducing bugs and making the system more difficult to understand and maintain. For example, we could start developing our systems as monoliths and slowly transition them towards complex microservices, instead of diving right into a complex microservice architecture. :)

Brooks's Law 🔗

Statement: Adding manpower to a late software project makes it later.

Source: Fred Brooks, an American computer scientist, coined Brooks's Law in his 1975 book The Mythical Man-Month: Essays on Software Engineering.

Explanation: This law suggests that adding more people to a project that is already behind schedule is likely to further delay its completion. Communication overhead and the time required for new team members to become productive can contribute to this delay. And as the team grows, the organizational structure becomes more complex. This can lead to confusion, bureaucracy, and decision-making delays. In this case, it is harder to keep everyone on the same page, distribute work effectively and be productive because it is most likely that some work causes friction inside different teams, or between teams.

Linus's Law 🔗

Statement: "Given enough eyeballs, all bugs are shallow"

Source: Linus's Law was coined by Eric S. Raymond in his 1997 essay "The Cathedral and the Bazaar: Musings on Linux and Open Source by an Accidental Revolutionary". It is named after Linus Torvalds, the creator of the Linux kernel. Despite the name, the book talks about two different free software development models.

Cathedral model, in which source code is available with each software release, but code developed between releases is restricted to an exclusive group of software developers
Bazaar model - in which the code is developed over the Internet in view of the public. Here, he credits Linus Torvalds, leader of the Linux kernel project, as the inventor of this model. (hence the given law name)

Explanation: Linus's Law is closely tied to the open-source software development model, where the source code of a program is made available to the public. By allowing a broad community of developers to scrutinize and contribute to the code, the theory is that the software can benefit from a collective effort to identify and resolve problems. In other words, the more people who have access to and review the source code, the more likely it is that any flaws will be identified and addressed, so the more eyes on a given source code, the fewer errors.

I think we can also extrapolate this to something related to the usage of a particular library. The more people use it, the more likely it is to create a stable library. This is one of the reasons that as an architect, I always advise and recommend using well-established libraries and packages.

Knuth’s Optimization Principle or the Premature Optimization principle 🔗

Statement: "Premature optimization is the root of all evil".

Source: Coined by Donald Knuth, an American computer scientist who is considered one of the fathers of computer science.

Explanation: It is often cited as a warning against premature optimization, which is the practice of optimizing code before it is necessary to do so.

The principle states that it is usually better to write straightforward, understandable code first, and then only optimize it if the performance is not good enough. This is because premature optimization can often lead to buggy code that is difficult to maintain.

I think this goes hand in hand with YAGNI, stating that we need to optimize when we really need to optimize, and not anticipate the optimizations that we will (maybe) need. In regards to this rule, but not necessarily related to optimizing code, I always advise teams to keep things simple when it comes to writing code.

Parkinson’s Law 🔗

Statement: "Work expands so as to fill the time available for its completion" or "Work expands so as to fill the allotted time."

Source: It was formulated by Cyril Northcote Parkinson, a British historian and author, in his 1955 essay "Parkinson's Law or The Pursuit of Progress".

Explanation: Parkinson's Law is often cited as a way of explaining why projects often take longer than expected. It is also used to argue against the idea of setting unrealistic deadlines. This law says that if you give people more time to do something, they will take more time to do it. This applies to software development because when we have a lot of time to complete a task, we may procrastinate or do unnecessary work to fill the time. This can lead to delays, cost overruns, and poor quality. Crazy deadlines should be the solution to prevent this 'rule' from being applied. A way to prevent this is thorough planning, task breakdown, delegation, discussion and estimations.

Conclusion 🔗

These are just a few of the laws we encounter in our software development world. These are some nice-to-know principles that some smart people came up with. If you have other favorite laws that I didn't cover, drop me a message and I'll add them.

Code-first gRPC

2023-12-05T00:00:00Z

Code-first gRPC or how to add gRPC to an existing app 🔗

There are cases when we are not lucky enough to start green-field projects, and we are not able to add the technologies we want or need from the project inception. In these cases, when it comes to using gRPC we can still retrofit it by leveraging an awesome library build by Mark Gravell.

Exposing code-first gRPC data types 🔗

To add gRPC support for an existing app we would need to install protobuf-net.Grpc package and to expose the types and operations by annotating them with some attributes. Below there are two types that we will use to be our request/response types. These are annotated with [DataContract], and [DataMember(Order = 1)].

Defining types

    [DataContract]
    public class PersonRequest
    {
        [DataMember(Order = 1)]
        public string Name { get; set; }
    }

    [DataContract]
    public class PersonResponse
    {
        [DataMember(Order = 1)]
        public string Message { get; set; }
    }

Once we define the types that we will use, we would need to define an interface that exposes our operations. In our case, we will have only one operation that will behave like a classic request/response. And by that I mean that is not streaming from client or server-side.

Title

[ServiceContract]
public interface IPersonContract
{
    Task<PersonResponse> SayHi(PersonRequest request, CallContext context = default);
}

This interface is our contract, and what we want to expose to consumers. It is up to you how you pack these types, either in the same gRPC project, or as a separate class library. I choose to have a separate class library because it is easier to share between different projects. Another reason is that I didn't want to reference the gRPC service directly in the consumer.

The next step is to take this interface and actually provide an implementation for the operations listed. This project is a regular gRPC service template, in which we install the protobuf-net.Grpc.AspNetCore NuGet package and enable the corresponding middleware builder.Services.AddCodeFirstGrpc(); in Program.cs.

You will notice that unlike using gRPC in a new project, in here we won't have code that is generated for us, but we will this interface that will be the 'definition' for our gRPC service. So when we give the actual implementation, we will implement what is specified in the interface, and not extend a generated base class as before.

Title


 public class PersonService : IPersonContract
 {
   public Task<PersonResponse> SayHi(PersonRequest request, CallContext context = default)
   {
         return Task.FromResult(
              new PersonResponse
              {
                  Message = $"Hello {request.Name}"
              });
   }
 }

Consuming the code-first gRPC service 🔗

Once we provide an actual implementation we can create a project that consumes our gRPC service. In this case I will use a console app and install 2 NuGet packages: protobuf-net.Grpc and Grpc.Net.Client. The first one allows us to work with gRPC code-first approach. The second allows us to call to call gRPC services.

After package install step we need to make sure we have access to the interface that exposes the types and operations. Depending on how you organized your code you need add a project reference. In my case I have a separate project that holds these types, and I needed to add the reference to the SharedContracts class library. With all being done, now we can call the gRPC service.

Title

using Grpc.Net.Client;
using ProtoBuf.Grpc.Client;
using SharedContracts;

Console.WriteLine("Hello, World!");
using var channel = GrpcChannel.ForAddress("https://localhost:7251");
var client = channel.CreateGrpcService<IPersonContract>();

var reply = await client.Unary(
    new PersonRequest { Name = "Gigi Dev" });

Console.WriteLine($"Greeting: {reply.Message}");

As you notice, we still need a channel that points to the gRPC service location, but we don't use the base client that is generated for us by the protoc compiler, we obtain a service instance ourselves by calling .CreateGrpcService<IPersonContract>();.

Another difference will be that we don't have a .proto file in our application that is shared between the service and the consumer of our service. Instead, we share C# code, by referencing it inside our consumer.

Summary 🔗

If you want to add gRPC to an existing project, let's say, a WCF one, you can do it without writing from scratch a .proto file that replicates your existing types and operations. This save some precious time and still gives you the perks of working with gRPC. The downside is that you won't have the interoperability you get when you work with Protocol Buffers. Those .proto files are agnostic and can be interpreted by different programming languages, giving you some flexibility. When you use the Code-First gRPC approach, you won't have that, since you are sharing C# code between your projects.

PS: If you want to actually execute the code I used, fill this form and you will receive the zip file directly in your inbox.

How to mimic response headers in gRPC

2023-11-13T00:00:00Z

How to mimic response headers in gRPC 🔗

gRPC trailers are a fascinating aspect of the gRPC that often receives less attention than the core request-response mechanism. They play a role in communication between gRPC clients and servers by providing additional metadata or information after the main response message.

What Are gRPC Trailers? 🔗

Trailers are part of the HTTP/2 protocol that carry additional metadata about a resonse. They allow servers to send extra information with the response. Usually, this information doesn't fit in the response message itself and can't be added to HTTP protocol headers collection. This is because the protocol is one level above the gRPC response and we are interested in the gRPC context and content.

gRPC uses trailers by default for two scenarios:

to support streaming
to send a grpc status code after the content

For example, when an error occurs, the Status(grpc-status) and Status-Message are delivered in the Trailers section

So basically, if we remember how a HTTP response looks like, we have:

Headers (or header fiels/header properties)
Body - the actual response content
Status code - indicating the status of our Response( 404, 200, etc.)

If we look at the picture below, we will notice that there are several gRPC responses inside the same response body. This is dependent of the gRPC method type that we have. For a Server-streaming method type we will have several reponses, and for all the rest, just one.

After all the responses, we see the gRPC trailers, which is sent only after all the response messages are sent.

Adding trailers in .NET 🔗

In .NET gRPC trailers are represented like a Metadata type, which is basically a dictionary that allows us to add key-value pairs from the server implementation. In our code, the type ServerCallContext contains info about both the current request and the response, and allows us to manage a few things. One of those things is ResponseTrailers. So, to add something in the ResponseTrailers, we simply create a Metadata.Entry object and we pass the key and value. If we need to add more than one key and value, we can also do that.

        public override Task<GrpcResponse> SayHello(GrpcRequest request, ServerCallContext context)
        {
            Metadata.Entry myHeader = new Metadata.Entry("my-fake-header", "grpc-header");
            context.ResponseTrailers.Add(myHeader);

            return Task.FromResult(new GrpcResponse
            {
                Message = "Hello " + request.Name
            });
        }

Conclusion 🔗

gRPC trailers are an often overlooked but invaluable part of gRPC. Their ability to carry additional metadata beyond the main response is instrumental in improving error handling, providing contextual information, and enhancing the flexibility of the protocol. Developers leveraging gRPC can harness trailers to transmit crucial details, streamline error handling, and enrich the client-server communication with valuable context. Understanding and utilizing gRPC trailers can significantly enhance the efficiency and effectiveness of gRPC-based applications.

gRPC vs REST

2023-11-02T00:00:00Z

Context 🔗

Both gRPC and REST are different architectural approaches for building distributed systems, each with its own fundamental characteristics. Both have their own place in the application ecosystem. The main visible difference being the context in which they are used. REST is more for public-facing APIs and gRPC for downstream APIs. In modern architectures, both gRPC and REST have their rightful place. Even though gRPC is fairly new to the game, it has it's own merits and it will never replace REST. REST(or HTTP APIs to be more specific) will continue to be the 'de facto' standard for creating APIs in the WEB world.

Underlying Principles and Architecture 🔗

Explain the fundamental architectural differences between gRPC and REST. Discuss how gRPC is based on Protocol Buffers and HTTP/2, while REST uses standard HTTP methods and typically exchanges data in formats like JSON or XML.

gRPC 🔗

gRPC uses HTTP/2 protocol. This gives us all the perks of using a new protocol version like: performance, reduced latency, and optimized network utilization.
gRPC uses Protocol Buffers (protobuf) as its Interface Definition Language (IDL). This is a special language in which we define the types(messages) that can be handled by the server, and service operations. This allows us to define what the server exposes in a language-agnostic way.
gRPC requests can be only of type POST
Call-a-method look and feel - for us, developers, with gRPC we call methods and pass parameters to the methods, and we get objects as a response

REST 🔗

REST APIs can use HTTP/1 or HTTP/2
The definition of a REST API is usually exposed trough a standard like Open API, and tools like Swagger
REST APIs use the standard HTTP methods (GET, POST, PUT, DELETE, etc.) to manipulate resources identified by URIs. Often these are used to perform CRUD(Create, Read, Update, Delete) operations
Make-a-request-to-an endpoint approach - for us, developers with REST APIs, we call endpoints utilizing HTTPClients, and passing in querystrings, request bodies and expecting the response back

Performance and Efficiency Comparison 🔗

Protocol Buffers 🔗

uses binary serialization format which is more compact and ligthweight(in some cases)
is not always human-readable( but we have tools to aid with that) e.g: Postman, Kreya, Kalisto,
is lightweight when it comes to data transmission over the network(due to its binary format and compression)
offer a high level of schema flexibility and extensibility. They allows for backward and forward compatibility through versioning and evolving message schemas without breaking changes, making them suitable for applications where data structures might evolve over time.
steep and complex learning curve, more setup
strongly typed

REST 🔗

is a text-based serialisation format
is human readable usually using JSON or XML
more heavy-weight for network data transfer due to the format
offer a high level of schema flexibility and extensibility. Thisflexibility allows for easy serialization of different types of data structures, it can lead to challenges in maintaining data consistency and handling schema evolution across different versions of an API.
easy to understand and simple structure
lack of strict typing

Service Contracts and Code Generation 🔗

gRPC 🔗

has a strict and well-defined service contract, in which we can specify the methods and their parameters and the message types.
code-generation out of the box
promotes a rigid an strongly typed API definition.
straightforward interoperability between different programming languages due to the consistent code generation from the well-defined service contract.

REST 🔗

has flexible and loosely defined service contracts relying on HTTP methods and standard data formats like JSON or XML
no strict standards or structured schema definitions allowing us to define and design services how we want
due to less strict service definitions, it can lead to less consistency in how APIs are implemented in various programming languages. This is usually done using third-party tooling

Tooling and Ecosystem Support 🔗

gRPC provides a more standardized and uniform way of defining APIs and generating code across multiple languages, leading to consistent development experiences. REST ecosystem is more descentralized. We can find a wide array of frameworks and tooling, providing flexibility and options for developers but may lack uniformity.

while gRPC's ecosystem is more standardized and centralized, providing uniform tooling and library support, the REST ecosystem offers extensive diversity and flexibility, leading to a more varied developer experience based on chosen frameworks and tools. Both ecosystems have their respective strengths and benefits, allowing developers to choose based on their specific needs, preferences, and project requirements.

Use Cases and Suitability 🔗

gRPC 🔗

high-performance applications where low latency and high throughput are essential. It uses HTTP/2 and binary serialization, making it faster and more efficient than REST in terms of data transfer.
microservices environments, gRPC's strong typing and well-defined service contracts streamline communication between microservices. We basically have to have access to the .profo file and we are good to consume the API that exposes the file. It supports bidirectional streaming that can be an advantage for distributed systems.
Polyglot/wanna be polyglot environments - the code-generation for various languages from the service contract(.proto file) is makes a consistent experience accross different languages. This allows expose and consume services from different ecosystems.
limited browser support - We have gRPC-Web that extends gRPC support to browser-based applications, its full capabilities and features might not be readily available or as seamless as with native gRPC usage in non-browser environments.

REST 🔗

due to the textual representation we can say that it has higher overhead and slower performance compared to gRPC
for all apps, and public-facing APIs
the format of the request/response must be known by the parts trying to communicate
fully supported in browser apps without third party tooling

Conclusion and Recommendations: 🔗

In summary, the choice between gRPC and REST depends on various factors such as performance requirements, interoperability, ease of use, and the specific needs of the application. gRPC is ideal for high-performance, microservices, and polyglot environments, whereas REST is more suitable for simpler, publicly accessible APIs and when browser compatibility and human readability are prioritized. Understanding the trade-offs and specific use cases helps in making an informed decision regarding the best-fit technology for a given scenario.

PS: Let me know if I forgot anything

Configuring gRPC clients in .NET

2023-06-13T00:00:00Z

Configuring gRPC clients in .NET is similar to what we would configure when we use HTTP Clients. The NuGet package that will allow us to use gRPC clients, is Grpc.NET.ClientFactory. This allows us to build on top of the IHttpClientFactory by providing us with the necessary GrpcClientFactoryOptions we use to customize our globally scoped clients.

Underneath it all, a gRPC client is a special kind of HTTPClient that knows how to handle messages at a lower level, in a construct called 'channel'.

  services
            .AddHttpClient(name)
            .ConfigurePrimaryHttpMessageHandler(() =>
            {
                // Set PrimaryHandler to null so we can track whether the user
                // set a value or not. If they didn't set their own handler then
                // one will be created by PostConfigure.
                return null!;
            });

We configure our gRPC clients globally in Program.cs, just as we configure any regular HTTP Client, by using the extension method, and pointing it to the right server address.


builder.Services
    .AddGrpcClient<SpeakerServiceDefinition.SpeakerServiceDefinitionClient>
    (
    o => { o.Address = new Uri("https://localhost:7226"); }
    )

By default, the AddGrpcClient, configures the gRPC clients as being transient.

Configuring gRPC client channels 🔗

We can configure several aspects of the gRPC channels, which resemble the configurations available for Kestrel. Most of these configurations pertain to the size of the transported data in bytes.

For example, below, you can see that the MaxReceiveMessageSize - referring to gRPC data is configured to be 100 bytes. This means that if the server sends a message that exceeds this limit, it will cause a ResourceExhausted exception in the consumer app.RpcException: Status(StatusCode="ResourceExhausted", Detail="Received message exceeds the maximum configured message size.")

builder.Services 
    .AddGrpcClient<SpeakerServiceDefinition.SpeakerServiceDefinitionClient> 
    ( 
     o => { o.Address = new Uri("https://localhost:7226"); }
    ) 
     .ConfigureChannel(o => 
     {  
         o.MaxReceiveMessageSize = 100; 
         o.MaxRetryBufferSize = 100;  
         o.MaxSendMessageSize = 100; 
     })

In a similar way, we can configure the MaxSendMessageSize property. This will prevent us from sending payloads that exceed what is configured globally.

We will get an exception that has the ResourceExhausted status code. This time, the exception happens when we call the server, and not when we get a response from it.

Grpc.Core.RpcException: 'Status(StatusCode="ResourceExhausted", Detail="Sending message exceeds the maximum configured message size.")'

The MaxRetryBufferSize is used when we have a retry policy in place, as a safety measure.

When a request fails, it gets added to the retry buffer. Then, the requests in the buffer are attempted again during subsequent retries. If the specified MaxRetryBufferSize is exceeded by the buffer size, new requests are not added to the buffer, and retries are not attempted.

This way, excessive memory consumption is prevented, and the buffer it's not allowed to grow indefinitely.

We can also configure the CompressionProviders and channel-level Credentials

Specifying a retry or a hedging policy 🔗

When configuring gRPC clients, we have the ability to specify whether a retry or a hedging policy is being used. All we need to do is create a policy and pass it as an option.

var retryPolicy = new MethodConfig
{
    Names = { MethodName.Default },
    RetryPolicy = new RetryPolicy
    {
        MaxAttempts = 5,
        InitialBackoff = TimeSpan.FromSeconds(1),
        MaxBackoff = TimeSpan.FromSeconds(0.5),
        BackoffMultiplier = 1,
        RetryableStatusCodes = { StatusCode.Internal }
    }
};


builder.Services
    .AddGrpcClient<SpeakerServiceDefinition.SpeakerServiceDefinitionClient>
    (
    o => { o.Address = new Uri("https://localhost:7226"); }
    )
     .ConfigureChannel(o =>
     {
         o.ServiceConfig = new ServiceConfig()
         {
             MethodConfigs = {
                 retryPolicy
             }
         };
      
     });

With everything configured we now can inject our client in controllers:

  private readonly SpeakerServiceDefinition.SpeakerServiceDefinitionClient speakerService;

        public HomeController(SpeakerServiceDefinition.SpeakerServiceDefinitionClient speakerService)
        {
            this.speakerService = speakerService;
        }

Now that you know how to configure gRPC clients, you can enable gRPC server reflection on your server.

Enabling gRPC server reflection

2022-12-13T00:00:00Z

Enabling gRPC server reflection will allow you to easily call your gRPC services from Postman without actually loading the protofile .

PostMan will help you test your gRPC services, by giving you the same look and feel as a you would have with a traditional HTTP API.

gRPC uses binary serialization, which means that is not human readable as JSON is. Is still possible to use grpcurl or similar tools, but you will not be able to decipher binary. Having the right tools will help you understand gRPC faster, because it has a slightly different vocabulary.

When you open PostMan and click the New button , you can choose to issue gRPC requests. Thankfully, this is not in beta anymore.

PostMan New menu options

To issue a gRPC request, you will need to specify the URL of the server (as you would do with a regular RESTful API), and then give PostMan access to the proto file that is implemented on the server. In this case, you need to help the tool a bit, so you can gain access to available functionality.

To do that you can simply import the proto file or let PostMan discover what is available.

In this case we will use the second option, because we would want our service operations to be somehow discoverable.

Different ways of 'accessing' the proto file contract

Now, if we try to click the highlighted option, we will get a big red error. This is as if our server throws an Unimplemented exception from a method.

In reality, if we look at the logs, it actually does throw that kind of exception. :)

info: Grpc.AspNetCore.Server.Internal.ServerCallHandlerFactory[1]
      Service 'grpc.reflection.v1alpha.ServerReflection' is unimplemented.

Enabling gRPC server reflection requires a few code tweaks because we actually need to an implementation that allows reflection over our grPC services.

First, install Grpc.AspNetCore.Server.Reflection NuGet package. This will contain the ServerReflection implementation that will we need, that allows external services and tools to discover existing methods

Next, we need to add the middleware and then map the incoming gRPC requests to the Reflection Service.

builder.Services.AddGrpcReflection();

IWebHostEnvironment env = app.Environment;
if (env.IsDevelopment())
{
   app.MapGrpcReflectionService();
}

Once you did this, PostMan will successfully discover the available gRPC methods, and you will be able to call invoke these from the UI

gRPC methods

That's it! A package and a few lines of code and you will enable gRPC server reflection.

Using custom media types in .NET

2022-04-01T00:00:00Z

How to use and create custom mime types in .NET? How to respond to different mime-types in your Web API? Use the same HTTP Verb but hit different actions based on the Content-Type header value? Have 2 methods that have the same number of parameters and respond to the same HTTP Verb?

These are questions that some of the developers seek answers to.

Accept & Content-Type 🔗

There are 2 very important headers that are often overlooked, Accept and Content-Type, and play a major role in a process called Content-Negotiation.

Accept header
With this header, the API consumer tells the server what is the mime type it expects as the format for the response.
eg. Accept: application/json or Accept: application/xml.
If the server can't build a response with the requested format, it will return a 406 - Not Acceptable status code.

Content-Type
Describes the format of the body of the request that is sent to the server or to the client. This tells the server: "Hey, the body you will receive has this format, can you interpret it?"
If the server can't read the content of the body, it will return a 415 Unsupported Media Type status code_._

Content-Negotiation is the process that happens with every request, where basically the two parties involved (i.e the Server and the Consumer/Client) do exactly that. : negotiate on the content. Depending on the format send as value for these 2 header properties, the result can differ.

When we talk about APIs or REST-ful APIs we implicitly talk about different representations of resources.

Introducing the problem 🔗

Let's say we have an API that deals with speakers. For these, we store all kinds of info, but not all are needed every time. Maybe you need to return a full object in one scenario, and just a few properties in another one, like below.

   public class SpeakerModel
    {    
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public string Bio { get; set; }
        public string JobTitle { get; set; }
        public string Website { get; set; }
        public string Email { get; set; }
        public string TwitterHandle { get; set; }
        public string CompanyName { get; set; }
        public string Address { get; set; }
        public string Phone { get; set; }
        public string PassportDetails { get; set; }
    }

public class TrimmedSpeakerModel
 {    
        public int Id { get; set; }      
        public string FirstName { get; set; }
        public string LastName { get; set; }
}

To achieve this, people end up creating new endpoints because the platform forces us to do so, in a way. We have the controller and in the controller we implement implement 2 actions, with different name, and different routes.

/api/speakers and /api/speakers/trimmed are basically two representations of the same resource. It shouldn't matter what scenario you are in, the endpoint should still be something similar to /api/speakers to the outside world.

In the example below we focus on the output, and not the logic in the action.

        [HttpGet("{speakerId}")]
        public IActionResult GetSpeakerFull([FromQuery] int speakerId)
        {
           return Ok(new SpeakerModel());
        }

        [HttpGet("{speakerId}")]
        public IActionResult GetSpeakerTrimmed([FromQuery] int speakerId)
        {
            return Ok(new SpeakerTrimmedDto());
        }

Something like this would be possible without getting an error from the routing mechanism. We know we have a GET request, but which one of the two actions should be selected? We need to help the framework to distinguish between the two of them.

Introducing media types(MIME types) 🔗

A media type (also known as a Multipurpose Internet Mail Extensions or MIME type) indicates the nature and format of a document, file, or assortment of bytes. MIME types are defined and standardized in IETF's RFC 6838.

Custom media types 🔗

A custom media type is a media type that we can create, often containg vnd as . This media type is significant to the specific business or domain.
You will often find vendor-specific media types used by different businesses as a mean to address specific customers trough the same api. There are hundreds of vendor-specific media types registered with IANA. Such example can be application/vnd.mspowerpoint.
GitHub uses them in their API, and a lot of other businesses.

Media type structure 🔗

Media type structure

Responding to media types in controllers 🔗

To respond to a specific media type in our action, all you have to do is annotate with the [Consumes("")] attribute, passing the value of your media type.

This attribute will allow us to have actions that return different representations of the same resource.

        [HttpGet("{speakerId}")]
      [Consumes("vnd.speaker.trimmed")]
        public IActionResult GetSpeakerTrimmed([FromQuery] int speakerId)
        {
            return Ok(new SpeakerTrimmedDto());
        }

You will have to send Content-Type : vnd.speaker.trimmed when you make the request, to hit the action.

In a similar manner you can use the [Produces("")] attribute to help the routing mechanism when you want a specific format returned. This attribute will look after Accept header value. Bear in mind that it will work out of the box only with the mime types supported by the framework. Otherwise you will need to create an OutputFormatter, and register it.

In summary 🔗

The approach with media types can be used for versioning too. You can read more about versioning your API here.

You can create your custom vendor-specific mime types, and include versions in them. From there you leave the routing mechanism to do its job.

Use this wisely, because currently It will cause a swagger loading error. I'm still looking for a way around it. If you know how, drop a comment or a DM

The .NET Docs Show - Versioning REST APIs

2021-05-11T00:00:00Z

How to build REST-ful APIs

2021-03-02T00:00:00Z

Thank you Edwin van Wijk and Sander Molenkamp for inviting me.

You can see more interesting videos on DotNETFlix channel on different topics, or read about REST

Naming your REST endpoints

2020-11-19T00:00:00Z

How to name your REST endpoint? How does your endpoint look? Are there any guidelines or best practices? How to name your endpoints?

A short introduction 🔗

We often use APIs to implement CRUD operations, or most APIs start like this, but all of them evolve over time.
CRUD is an acronym that stands for Create, Read, Update, Delete. And these are all the operations that you can apply to a specific resource.

Let's take childish example, and say you need to manage pets for a veterinary cabinet and you are interested in cats:

/api/getAllCats- wouldn't /api/cats be easier to remember?
/api/newCat - how about /api/cats and use POST as HTTP Verb?
/api/getBlackCats- why should you have a different endpoint? /api/cats?color=black will have the same path, but the parameter value will change an get you a lot of flexibility
/api/getCatsOwners- how about /api/cats/{id}/owners- this way you will know exactly to which cat you are reffering. The one with the {id} in the URL path.
/api/getHungerLevel- hunger level of...? cat? which cat? maybe is youru hunger level?

If you look at the endpoints, are very hard to remember, and once you add more operations, it will be even harder to remember and harder to manage. Plus, you have no reason to include get{something} in the endpoint or have tons of endpoints. The HTTP verb will be the one that tells what operation you are doing. Either is a GET, a POST or something else. KISS, as in code, also applies here. And more than that, we need to keep in mind that we need to leverage the underlying protocol as much as we can.

In my opinion, an endpoint in a REST API should be self-explanatory. Just by looking at the URL, you( and the server) should be able to tell what is the resource it handles without needing a manual.

One ot the things REST is trying to do, is to remove the uglyness we all dealt with in SOAP. SOAP exposed a set of operations in a WSDL file, and to 'call' those operations we made a single type of call(POST or GET). REST is trying to get rid of that paradigm and get us closer to the underlying protocol.

Luckily, if you are nostalgic(or not) we have tools like Swagger and the Open API standard to help us with the documentation, but even so, and URL should express intent in the 'eyes' of the consumer.

COOL URI's don't change.

Let's look at the 2 endpoints that you will need in a REST API.

An endpoint for the collection 🔗

/api/cats

This will allow you 2 operations:

retrieve the collection by HTTP GET (a read)
Create a new resource by using HTTP POST (a create)

An endpoint for a specific item 🔗

/api/pets/{id}

This will allow you 4 operations:

retrieve the item by using HTTP GET(a read)
update an existing resource by using HTTP PUT(an update) or HTTP PATCH
delete and existing resource by using HTTP DELETE(a delete)

Any hierarchical resource can be represented further in the URL path, but the convention remains, and applies down in the hierarchy.

Let's take the example of wanting to represent the owners of a specific cat:

/api/cats/{id}/owners

Looking at this URL we realize that in the cats collection, we are interested in the specific {id} of the cats, and from this specific cat, we want the owners collection.

When we obtain the list of owners, we might be interest to obtain a specific one, and we can take another step : /api/cats/{id}/owners/{ownerid}

You are not forced to model your data and store it in the database according to the endpoints, or the other way a round. Remember, in REST, you work with representations of resources, and those representations are handled by you. At the server level, for more decoupling and simplicity, you should use DTOs to transform or aggregate data.

Takeaways 🔗

Name your endpoints in such a way to have meaning for the business and your consumers
You don't need a different endpoint to represent a new operation. You can give meaning to your request by using the right HTTP verb
You can use GET, POST to the same endpoint /api/cats : the end result will be different.
you need two endpoints to represent major operations on a resource
Variations of specific resources can be represented as parameters in the query string, not different endpoints.

In conclusion, it is up to you how you shape your endpoints. There is no constraint in this. As long as it makes sense for the business, expresses the intent, and is specific enough.

The meaning for each request/response should be added by using the right HTTP Verbs, headers and status codes.

.NET Core with NGINX on Linux

2020-10-07T00:00:00Z

Having .NET Core with NGINX on Linux is easier that you might imagine. In this article I will talk about my experience related to NGINX and what it takes to configure it for the first time. If you come from an IIS/Windows world like me, where you know everything by heart, the declarative approach in NGINX might be a bit odd.

I already have Kestrel, why do I need something else? 🔗

Kestrel is the default server implementation for ASP.NET Core, and it is super fast, cross-platform, customizable and it can run on its own. It looks like it is the perfect server, but it was lacking a lot of features related to security. Another thing about Kestrel is that "used as an edge server without a reverse proxy server doesn't support sharing the same IP and port among multiple processes".

Although is not required, it is recommend to have a reverse proxy in front of Kestrel because it will give you an extra layer of configuration and defense and integrates smoothly with the existing infrastructure.

A proxy server is a go‑between or intermediary server that forwards requests for content from multiple clients to different servers across the Internet. A reverse proxy server is a type of proxy server that typically sits behind the firewall in a private network and directs client requests to the appropriate backend server. A reverse proxy provides an additional level of abstraction and control to ensure the smooth flow of network traffic between clients and servers.

https://www.nginx.com/resources/glossary/reverse-proxy-server/

What is NGINX? 🔗

NGINX is an open source software for web serving, load balancing, media streaming, that also has reverse proxy capabilities. One of the goals behind NGINX was to create the fastest web server out there. Now, is one of the most popular servers out there.

Installing NGINX on Linux 🔗

Depending on your Linux distribution the package manager might differ. I had Red Hat sudo yum install nginx did the trick. After a successful installation you will find the files and folders for NGINX under /etc/nginx path on the server looking pretty much like this( without the highlighted folders)

nginx structure

One of the most important files out there is the nginx.conf file that will contain or reference other configurations for your web apps. Bear in mind that, in order to be able to start NGINX server this configuration will have to be valid.

Configuring NGINX for all your apps 🔗

Now, I’ve cleaned up a bit the default nginx.conf and it looks like this:

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
include /usr/share/nginx/modules/*.conf;
events {
    worker_connections 1024;
}

http {
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
    '$status $body_bytes_sent "$http_referer" '
    '"$http_user_agent" "$http_x_forwarded_for"';
    access_log /var/log/nginx/access.log main;
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    # Load modular configuration files from the /etc/nginx/conf.d directory.
    # See http://nginx.org/en/docs/ngx_core_module.html#include
    # for more information.
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;

}

For easier formatting, I used Visual Studio Code with 2 extensions: Nginx configuration and Nginx Formatter.
At line 28, I’ve added an include statement because I want to place all my configurations for different website in separate files, in sites_enabled folder.

After that, I’ve created the sites_enabled folder, and the certs folder (that will contain certificates). In the sites_enabled folder, I’ve created a file named myapi.conf and inside it, I’ve added this:

server {
    server_name myserver;
    root /var/opt/myapps/ui;

    index index.html index.htm index.nginx-debian.html;

    location / {
        try_files $uri $uri/ /index.html;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }

    location /api {
        proxy_pass http://localhost:4906;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }
}

In the configuration file I have 2 'location' sections, one for an UI app, and one for the API. The two apps I want to be served from the same 'domain' but on a different path:

the ui app from the root like /myapp
the api from something deeper in the hierarchy like: /myapp/api

Once this is done, you can test the nginx configuration by running nginx -t -c /etc/nginx/nginx.conf in the terminal. If that is successful, you can go ahead, start NGINX server

Useful NGINX commands 🔗

sudo nginx service start

sudo nginx service restart

sudo nginx service status

In summary 🔗

We looked at how to configure .NET Core with NGINX on Linux, but the same configs will work on Windows also. The only thing you need to do besides configure NGINX is to run the API as a Linux Service, and to make sure is up.

In a following post we will add https in front of our API, because we need to care about security. :)

.NET API as a Linux Service

2020-10-06T00:00:00Z

.NET API as a Linux Service is just one of the many options when it comes to hosting.

One thing I love about .NET Core is that it runs everywhere. Running .NET APIs as Linux services, allows different organizations to reduce some costs by maybe reusing infrastructure. Before .NET Core, .NET was almost synonymous with Windows. The only server for .NET was IIS.

Now you have a ton of options when it comes to hosting your .NET applications.
You want to keep running it on Windows? You can host and install it as a Windows Service with NSSM. Do you want Kestrel instead of IIS Express? No worries, you can do that. Nowadays, sky is the limit when it comes to hosting a .NET API.
One thing you will need to do is to install .NET on the server. You can read here how to install .NET on different Linux distributions. (If you never did this or you are not an experienced Linux user).

What you need 🔗

- Putty or a way to connect to your Linux server
- sudo rights or execution rights on the server

Running an API as a Linux Service 🔗

If you have your API in good standing, versioned, and with the right status codes and you chose Kestrel, the only thing you need to do is to create a .service file and to put it on your Linux server. In my case, the API was hosted on a RedHat distribution.
The service content will be a file with the .service extension (let's call the file myapi.service), placed under /etc/systemd/system path.

The .service file will contain info related to what it will need to run and from where, and a few flags.

[Unit]
Description=Awesome API
[Service]
WorkingDirectory=/var/opt/myapps/myapi
ExecStart=/usr/bin/dotnet /var/opt/myapps/myapi/MyApi.dll
Restart=always
RestartSec=10
SyslogIdentifier=myapi
User=root
Environment=ASPNETCORE_ENVIRONMENT=Development
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
[Install]
WantedBy=multi-user.target

Assuming you have sudo rights, you will need to start the service by running systemctl start myapi.service

Useful linux commands 🔗

systemctl stop myapi.service stops your service

systemctl start myapi.service starts your service

systemctl status myapi.service returns the status of your service. Is useful when you want to make sure the service is running or for debugging purposes. The response will contain some aditional info, depending on what you have configure, but it will look pretty much like this:

Once you have your NET API as a Linux Service up and running, you might need to make it run on HTTPS.
You'll see in another article how you can configure NGINX Reverse proxy to have Https.

Status Codes for REST APIs

2020-07-16T00:00:00Z

When it comes to Status Codes for REST APIs, we are all in a hurry to deliver functionality and we often ignore them. Come as it may. We use what we get. And that's it.

REST as a concept should also be about meaning, longevity and empathy towards our API consumers. We should be able to look at a request/response in isolation and understand what is wrong or what happened.

Choosing Status Codes for REST APIs sometimes is not easy, but at least we should give this a thought.

In this article, I will talk about Status Codes for REST APIs: the most common and the ignored ones, and a few usage scenarios.

We all know that we have 5 categories when it comes to status codes. And depending on the response category we should be able to tell what happened with that request. Was the request bad? There is an error processing it?

Status Codes - Categories 🔗

1xx - Informational
2xx - Success
3xx - Redirect
4xx - Client Error
5xx - Server error

I've seen APIs where the status code was 200 OK, but the response body looked like this:

In this case, me or my app, as an API consumer...what should I understand? Was my request successfully processed, or.... am I unauthorized? #confusing. So don't do this in your APIs.

2xx - Sucess status codes 🔗

These are success status codes because they start with 2, but in particular, that code should express exactly what happened. You shouldn't return 200 OK for all the scenarios and then write an error in the body. (if you want to add meaning and have a well-rounded API.)

200 OK
When the response what processed with success, and usually has a response body.

201 Created - As a response for a POST request that has the effect of creating a new resource. This should be accompanied by a Location header indicating the location for the newly created resource

202 Accepted - For scenarios where there is no need for a response body. e.g for queuing something for later processing.
Also, this works very fine with the Location header, for polling scenarios, where you call the endpoint from time to time to see the status of a resource processing
204 No Content - usually as a response for a DELETE request

4xx - Client errors 🔗

400 - Bad Request
Bad Request is in my opinion, one of the most miss-used status codes. I've seen it returned when due to some business logic the request couldn't be processed, but the request was well formed.
Think about it - when the request is well-formed, it has the parameters, the body and everything all good, but is a business rule on the backend that prevents that request from being processed....is not a Bad Request. Is anything but a Bad Request.
When you see a Bad Request, the tendency is to look at the content of the request to see what is wrong, fix that, and issue the request again.

Dummy Scenario: Online Store. You can't create 2 products with the same name and brand.
401 - Unauthorized, 403 - Forbidden
404 - Not Found - resource is not there, or maybe it was deleted.
406 - Not acceptable - when the server can't return a response that matches the Accept header of the request. To force .NET to take the Accept header into consideration you will need to set a flag to true:

 services.AddControllers(setupAction =>
 {
    setupAction.ReturnHttpNotAcceptable = true;
  })

409 - Conflict - When there is a business rule that prevents you from creating that resource as a result of a POST. Another scenario can be with using PUT to update a specific resource, and due to its state, you can't.
For this, the RFCs mention the fact the PUT requests might have versions and updating one might give you conflict.

410 - Gone - used to mark something as not available anymore; like promotions...or out of stocks..maybe... or simply to show a soft delete
415 - Unsupported Media-Type; When the server can't understand the body of the request, due to a wrong Content-Type header, or limited capabilities on the server.
For example, if you try to send an XML in the request but the server doesn't know how to read XML, you should get this status code.
422 - Unprocessable Entity - the server understands the request, the request is well-formed but due to some rules, it can't be processed. It can be used instead of 409 - Conflict and also covers a lot of ground. You can configure this in Startup.cs by leveraging ApiBehaviourOptions like this:

           services.AddControllers()
                .ConfigureApiBehaviorOptions(setupAction =>
            {
                setupAction.InvalidModelStateResponseFactory = context =>
                {
                    var problemDetails = new ValidationProblemDetails(context.ModelState)
                    {
                        Type = "https://yourApi.com/modelvalidationproblem",
                        Title = "One or more model validation errors occurred.",
                        Status = StatusCodes.Status422UnprocessableEntity,
                        Detail = "See the errors property for details.",
                        Instance = context.HttpContext.Request.Path
                    };

                    problemDetails.Extensions.Add("traceId", context.HttpContext.TraceIdentifier);

                    return new UnprocessableEntityObjectResult(problemDetails)
                    {
                        ContentTypes = { "application/problem+json" }
                    };
                };
            });

This way, you can hook yourself to the ModelState and treat validation errors as 422 status codes instead of Bad requests if you need that. You can find more examples in the docs. As a result, ASP.NET higher than 2.1 generates RFC-7807 compliant responses.

As a side note, if you configure ApiBehaviour to return BadRequest for model validation, you won't need to scatter all over your controllers these lines of code:

if (ModelState.IsValid) 
 {
     return BadRequest(ModelState);
 }

Conclusion 🔗

Even though the most common status codes that might fit a lot of scenarios, we should bear in mind that there are around 63 of them!! Why? For us to use!
If we don't use "one size fits all" in terms of the technology we choose, why do we apply this on status codes?
If don't think about versioning, or headers, or HATEOAS in our APIs, at least we should have the right status codes.(and verbs, and naming :) )

Extending EF Core DbContext

2020-05-29T00:00:00Z

Entity Framework allows you to extend the DbContext class to add your own entities, extend existing entities, and customize them at runtime. All of these in a clean and simple manner, if you are willing to do so. It doesn't even matter if those entities don't have a table representation. You can do that by leveraging C# partial classes and methods. Extending EF Core DbContext is a common scenario, but I think we're often not aware of its real power.

The way I like to organize entities in my projects

Introducing OnModelCreatingPartial 🔗

Commonly your application context will be similar to this: a lot of DbSet that map to the database table object.

    public partial class ConferenceContext : DbContext
    {
        public ConferenceContext(DbContextOptions<ConferenceContext> options)
            : base(options)
        {
            this.Database.EnsureCreated();

        }

        public DbSet<Speaker> Speakers { get; set; }
        public DbSet<Talk> Talks { get; set; }


        protected override void OnModelCreating(ModelBuilder modelBuilder)
        {
            OnModelCreatingPartial(modelBuilder);
        }
        
        partial void OnModelCreatingPartial(ModelBuilder modelBuilder);
    }

You might notice the OnModelCreatingPartial method in the example above. I've noticed this recently after using a database-first approach in a small project. To be honest, it was really an "Aha!" moment, because if you look into DbContext class source, you will not find a reference to it.

This method gives you a simple and clean way to hook into OnModelCreating method to add customization for the extra-entities you might need.
If you are like me you keep an eye on performance or data transfer from the database into the project, you will use raw SQL queries. As a result, you will end up with many classes used only for specific scenarios.

Before EF Core 3.0 there was another datatype DbQuery that allowed you to specify that the entity T is used only for querying and not for inserts or other operations. Migrations and idempotent scripts generated are done in the same way, but above EF Core 3.0, everything is a DBSet.

It is up to you to tell EF Core that T has no key, like in the example below. You can read more about keyless entity types and the future of this in the Microsoft docs. As you see. extending EF Core DbContext is easy and you can use the approach you are comfortable with either with FluentApi or annotations.

    public partial class ConferenceContext
    {
        public DbSet<TicketSummary> TicketSummaries { get; set; }

        public void OnModelCreatingPartial(ModelBuilder modelBuilder)
        {
            modelBuilder.Entity<TicketSummary>().HasNoKey();
           
        }
    }

In this example, TicketSummary class is used to retrieve results from a raw SQL query. In that query, I make a join and cherry-pick a few columns. That is it. I have no such table called TicketSummary in my database. Instead, I used FluentApi to specify that there is no key for the entity.

Versioning REST APIs

2020-04-24T00:00:00Z

Headers or URL? 🔗

In the context of REST APIs there is a lot of confusion around versioning. Some people recommend versioning REST APIs by adding the version in the URL. Others don’t version at all, and others recommend versioning REST APIs using headers.
Nothing bad so far, but I’ve personally seen a lot of different APIs, that serve different domains and purposes that have a v1 in the URL. Not that is very bad, but the same APIs reach their end of life, with the same v1 in the URL. It’s hard to believe that was no change there since their inception. If so, why add a version in the first place?

I think that these APIs end up with having the v1 forever because the consumer apps are also controlled by the same organization or teams.

This way, the teams just go and change the consumer apps to accommodate the API changes, and that is it. They don’t have to worry about breaking something, somewhere, because they know and have full ownership over those changes.

But what if you would have and API exposed for consumers and you have no control over the consumer code? Would this change something in terms of having v1 forever embedded in your endpoints? For sure it would! You would be forced somehow not to break your consumers, or constrained by some SLAs or legal stuff to ensure backwards compatibility, and to be very transparent about your API changes.

More than than, you will need to ensure that nobody gets hurt by calling your API, and you don’t end up answering to support calls from them. This will make you think about designing your API changes carefully.
Now, let’s see how we can version.

The usual approach to versioning( URL versioning) 🔗

The most common approach to versioning is through URLs. You have our endpoints in a form that includes a version like: [https://myapp.com/api/v1/speakers](https://myapp.com/api/v1/resources).
In order to call anything from there, you need to add v1 and you are done.
If you are talking .NET and WEB API, is very easy to do that for every endpoint just by decorating the Controller with that version, and you are all set.

[Route("api/v1/speakers")]

The inventor of REST - Roy Fielding said in a tweet that:

REST should imply evolvability

If you correlate this with what Tim Berners-Lee said then you might have no reason to version in URL. Not in the path anyways.

COOL URIs don’t change

Tim Berners-Lee, 1998

Why not change the URLS? 🔗

Think about it. Sometimes you navigate to websites and you know the URL by heart. URLs matters for SEO, need to be discoverable, express intent and describe the content.
If you suddenly decide to reorganize a website, and you go around and change everything in terms of URLs there a big chance to lose users. Their bookmarks won’t work anymore, and they won’t be able to find the content they are interested in. That’s when people usually give up and move on and forget about you.

If you decide(hopefully) to increase the version, you might break all your clients. And remember, you can’t force your clients to move to the new version when you want.
Surely you can’t say: “From now on, all my consumers will use v2”. It is physically impossible, since you don’t have control over them, and each of them has different priorities.

Suddenly, taking everyone on board for the new version becomes a long process. You need to ensure backwards compatibility for who knows how long (read it as forever) and documentation.

More than that, let’s take another scenario. Microservices and data transfer in Microservices with HttpClients. You usually have somewhere the URLs hardcoded, in a JSON or something or even inside libs with that are distributed through some package manager. If you change the URLs, to change the version to v2, you will need to find all those places in your code where you have it ‘hardcoded’. PS: you know you forget all the places.
Versioning your REST API in URL, to me is not the best idea.

Versioning trough headers 🔗

Now I know is not the most common way to do versioning but is my personal preference. Why?

“Because cool URIs don’t change”.

Adding meaning and some kind of specificity to a request can be done in different ways, why do it through the URL itself. The URL should be self-describing, don’t pollute that with versioning-related pieces.

In my opinion, as long as that endpoint is very clear in terms of naming – is specific enough, gives a clear understanding of what is the resource it is supposed to handle you are all set.

You can add meaning to your requests very easily. You can add proper verbs, custom headers, to hydrate the request, to specify intent. Remember that a request should be understood in isolation, and HTTP is stateless.
This way you help a bit with content negotiation.
You add Accept header property to help the server understand what the client needs and expects, Content-Type to describe the request body, and so on.

In the same manner, you can add a custom header property that specifies what is the version that the client wants to call.

Using a library 🔗

Luckily there is an awesome library in .NET called Microsoft.AspNetCore.Mvc.Versioning that will speed up a lot of manual work. It will give you a lot of flexibility and config options, and your code won't be a mess.

You will need to configure it in Startup.cs with the behavior you want.

services.AddApiVersioning(o => o.ApiVersionReader =
               new HeaderApiVersionReader("api-version"));

Then, you can go ahead and decorate the controllers with the right API version attribute.

[Route("api/speakers")]
    [ApiController]
    [ApiVersion("1.0")]
    public class SpeakersController : ControllerBase
    {
        //code removed for brevity
    }

Using simple attributes, you are now allowed to have 2 controllers side by side, that have the same route. One of them has the previous version, and the second the new version. Using the same URL and without any changes will respond correctly to requests, as long as the correct header is specified in the request.

    [Route("api/speakers")]
    [ApiController]
    [ApiVersion("2.0")]
    public class Speakers2Controller : ControllerBase
    {
    }

When you issue a request to the API, you will need to have api-version header with the correct value specified. api-version:1.0 or api-version : 2.0 Based on that, the request will hit a controller on another.
You are not limited to only this kind of configuration.
You can assume a default version if this header is not there, or you can enforce a query parameter for the version, configure default behavior and error pages, and so on.
Everything is configurable inside Startup.cs

When to increase the version? 🔗

There is no clear answer to this. It depends on the number of changes and their magnitude. Be pragmatic about it, and don't take it to the extreme. An API version number is not the build number. Don't do that.
How often do you increase the version number is a matter of API design first. Ask yourself a few questions:

How many consumers you have? In what way are these clients affected by your changes? What is the development speed for your consumers? Are there legal/contract matters? (Maybe they don't have the same agility as you have)
Is it easy for you to maintain multiple versions of the same API?

In conclusion

Versioning REST APIs is not that hard, and REST itself is not bad. There is a certain amount of discipline to do this. You need to design the API with your consumers/clients in mind and take responsibility when you introduce changes.

If you find this intriguing, ping me on twitter. Let's chat!

View Razor changes without building the project

2020-04-05T00:00:00Z

How to view Razor changes without building the project. There is no need to build the project to see changes in Views.

When I was a junior developer I remember my team lead telling me:

No, you don't need to rebuild the solution if you modify something views

I've absorbed this phrase and kept telling it to my students. Until recently to realize that is not of actuality anymore. For many years after that, I stopped working in ASP MVC projects, having only APIS, angular, and React client apps.

Recently I've upgraded an MVC project from 2.2 to 3.1 and needed to make some changes in Views.

Nothing bad so far, I still remembered how it's done. Yey! It is like riding a bike.
Oddly enough, I had to rebuild the solution to see the changes made in Views and I was really annoyed, I had just static HTML and couldn't understand why I have to rebuild. Up until this moment, compilation of views was triggered by the editing. I started to dig around and did some research, and here's what I've found out.

Razor compilation is enabled by default only for build/publish 🔗

Razor compilation is enabled by default only for the build and publish scenarios, not for runtime aka when you edit the view.

Now, if you want that functionality back, you need to install a NuGet package: [Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation](https://www.nuget.org/packages/Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation/) and add the middleware and boom, it works.

services.AddControllersWithViews()
        .AddRazorRuntimeCompilation();

Conditional runtime compilation 🔗

Another method to obtain the same thing, which I really don't like is based on directives. This way, you can keep the default mode, but enable what you need only when you are debugging (running locally).

First, you need to start by editing your csproj file to add a condition on the package.

<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation"
Version="3.1.3" Condition="'$(Configuration)' == 'Debug'" />

After that, you need to make some adjustments in your startup file to add the condition. Start by adding a property to hold IWebHostEnvironment, and set the value from the controller.

  public Startup(IConfiguration configuration, IWebHostEnvironment env)
        {
            Configuration = configuration;
            HostEnvironment = env;
        }

        public IConfiguration Configuration { get; set; }

        public IWebHostEnvironment HostEnvironment { get; }

After you did that you need to add the #if condition to enable the 'dynamic' loading for the conditional runtime compilation

            var builder = services.AddControllersWithViews();
#if DEBUG
            if (HostEnvironment.IsDevelopment())
            {
                builder.AddRazorRuntimeCompilation();
            }
#endif

With this in mind, make sure you change the IWebHostEnviroment scattered around your Startup class, and point it to the newly introduced property. Is not the cleanest solution, I do not prefer this, but it does the job. More than that, we all lie to ourselves that, ok, I'm gonna change the default, and just comment the line of code before deploying. Only this will never happen.

In the official docs, they say that by using the conditional compilation you make sure that the published output uses the compiled views, are smaller in size, and it doesn't enable file watchers in production. All these might be true, but it doesn't make my developer experience nicer. What do you think?

From .NET 2.2 to 3.1 - Routing issues

2020-03-30T00:00:00Z

Having a website on 2.2, I thought that there is about the case to upgrade. Now or never I said. How hard can it be?

I went pretty smooth, by using the -> migration guide..until.... I've bumped into routing. I've spent a decent amount of time trying to debug the issue, without visible progress.

My issue was that my website had a public side and an Admin area where all the administration magic happens after login.

Changing from app.AddMvc() to app.UseEndpoints() is pretty easy just by changing this:

app.UseMvc(routes => {

routes.MapRoute( name: "areaRoute year", template: "{area:exists}/{controller}/{action}/{id?}", defaults: new { controller = "Home", action = "Index" } );} });

to this:

app.UseEndpoints(endpoints => { endpoints.MapControllerRoute( name: "areaRoute year", pattern: "{area:exists}/{controller}/{action}/{id?}", defaults: new {controller = "Home", action = "Index"} ); });

So the real changes in here are the template parameter name to pattern, and MapRoute to MapControllerRoute and the rest is pretty much the same.

So far so good, but my routes on the Admin area simply didn't work anymore. Everything on the admin was not accessible, and I got 404 in the browser. This led me to believe that my routes had an issue around authorization. I tried again and failed again, and I gave up.

Fortunately, we still have the option to ignore for now the UseEndpoints and fallback to the old version by setting a single property to false in ConfigureServices.
services.AddMvc(options => options.EnableEndpointRouting = false);
Now, by setting this you can use the old approach without any issues, just make sure you don't add the app.UseRouting() by any means.

Take 2 - try again 🔗

Renamed everything as it should be and looked a bit at the order of Midleware imports.

I can say that 3.1 middleware order matters even more than before. You must have

 app.UseRouting();
 //anything in between
 app.UseAuthentication();
 app.UseAuthorization();
 app.UseEndpoints(endpoints =>...);

My actual issue was that app.UseAuthentication() and app.UseAuthorization() order was reversed. I can't tell you why it worked in 2.2, but for sure doesn't work anymore in 3.1.

After this fix, I was able to have a fully working app migrated to 3.1, and now I use endpoints not routes.

Conclusion
We knew that order of the middlewares matters, but in this case there is a slight difference. Make sure you have .UseRouting(), any other middleware you need and then UseAuthentication, UseAuthorization, UseEndpoints

How to generate idempotent scripts from EF Core migrations

2020-03-23T00:00:00Z

Is it possible to generate idempotent scripts from EF Core migrations? Automatically? Yes, it is! But first, let's see what idempotency means.

What is an idempotent script? 🔗

A subroutine with side effects is idempotent if the system state remains the same after one or several calls, in other words, if the function from the system state space to itself associated to the subroutine is idempotent in the mathematical sense given in the definition;

Generally speaking, an idempotent script, no matter if it is written in PowerShell, bash or SQL on any other scripting language, will give you the luxury to run it over and over again, without the fear of breaking something. More than that, any script that might fall under unsupervised hands/system should have some 'safety' measures built-in.

Now, we know from HTTP concepts that GET and HEAD requests are idempotent and safe. But POST requests aren't neither safe nor idempotent.

The question is why? Well, first of all, by sending a POST request you end up creating new resources, and if you don't have a business rule to prevent requests with the same request body, you'll just have a lot of duplicates and nothing stopping you from creating them.

Why can't we apply the same rules when writing database scripts?

General idempotency guidelines in database scripts 🔗

You must write it in such a way that you check at least the most likely scenarios.
For example:

for a table creation - check first if the table exists, if yes, do nothing
for deleting a column - check if exists
for altering a column - check if exists

So on and so forth, but you get the point. You need to cover all the scenarios that can end up corrupting your database.

There are several options to manage your database scripts. With so many third-party or out-of-the-box tools, sometimes is difficult to even choose.
A few years back I remember using PostgreSQL as a database for a project, and I really enjoyed the syntax. We used to manually make idempotent scripts, tested them locally, then added them to a different repository and shipped them to production with Flywayy.

Generating idempotent scripts from EF Core migrations 🔗

Assuming you already have a migration added there are a few commands that are handy and with a few flags

generate script in CLI
dotnet ef migrations script {lastAppliedMigration} --startup-project MyApp --idempotent
By running the command you will get as a response the script in the CLI. Make sure you specify the last working migration in the placeholder. Without that, you will obtain the script for all migrations ever applied in the project.
generate the script in an .sql file under a specific location and in a specific file:dotnet ef migrations script {lastAppliedMigration} --idempotent --output {FolderName}/{sqlscriptname}.sql --startup-project MyApp

No matter the script you are running you can always add the --verbose flag to see what is executed with that script.

Real-life example: generating a script that adds Addresses to Person

dotnet ef migrations script MadeRequired --idempotent --output Scripts/Addresses.sql --startup-project Persons

Will generate this:


IF NOT EXISTS(SELECT \* FROM \[\_\_EFMigrationsHistory\] WHERE \[MigrationId\] = N'20200314111307\_Addresses')
 BEGIN
     CREATE TABLE \[Address\] (
         \[Id\] int NOT NULL IDENTITY,
         \[StreetName\] nvarchar(max) NULL,
         \[ZipCode\] nvarchar(max) NULL,
         \[City\] nvarchar(max) NULL,
         \[PersonId\] int NOT NULL,
         CONSTRAINT \[PK\_Address\] PRIMARY KEY (\[Id\]),
         CONSTRAINT \[FK\_Address\_Persons\_PersonId\] FOREIGN KEY (\[PersonId\]) REFERENCES [Persons]([Id]) ON DELETE CASCADE
     );
 END;
 GO
 IF NOT EXISTS(SELECT \* FROM \[\_\_EFMigrationsHistory\] WHERE \[MigrationId\] = N'20200314111307\_Addresses')
 BEGIN
     CREATE INDEX \[IX\_Address\_PersonId\] ON [Address]([PersonId]);
 END;
 GO
 IF NOT EXISTS(SELECT \* FROM \[\_\_EFMigrationsHistory\] WHERE \[MigrationId\] = N'20200314111307\_Addresses')
 BEGIN
     INSERT INTO \[\_\_EFMigrationsHistory\] (\[MigrationId\], \[ProductVersion\])
     VALUES (N'20200314111307\_Addresses', N'3.1.2');
 END;
 GO

As you can see, this script relies heavily on the __EFMigrationsHistory table, which is not exactly very...idempotent. So, my recommendation is to have another look at the generated scripts and customize and test them.

Conclusion 🔗

By using the right tools and knowing the right flags we can make our lives easier.

Working with EF Core Migrations

2020-03-20T00:00:00Z

How to create migrations in EF Core with SQL Server provider? How to handle migrations with EF Core? Migrations in a different library than your main project? These are questions we will try to respond in this article

After a few years working with other ORMs it was about time to come back to Entity Framework to see how it evolved.

The last time I worked with it, it had the .edmx designer. It was fun sometimes, but I remember having projects with huge databases that were a mess when you needed to update something.

Back then, we didn’t know about tools like Flyway or DbUp . Versioning database scripts or integrating them into the pipelines wasn't considered. We just used tools to sync everything in place: schema and data.

Entity Framework Code first approach 🔗

The code-first approach is one of the most common scenarios when talking about databases and .NET Core projects. When using this approach, you consider your C# code to be the source of truth. You extend the DbContext class and after that, you make the changes in the entity classes.

To be fair, I don't rely on migrations done from the codebase. I advise you to take control and generate idempotent SQL scripts from these migrations.

Adding an EF Core migration 🔗

We assume we already have a project and we want to add a change in one of the Entities, and we need to add a migration.
Assuming that you are using the CLI and you have an application with only one project and you are in the root folder hierarchy you will use something like this

dotnet ef migrations add {migrationName} --project {projectName}

Keep in mind that when running a command, you can also use paths. These are relative to the folder you are running them from the CLI. Usually the root of the project, the one with the .sln file.

dotnet ef migrations add {migrationName} --output-dir {../MyApp.Domain/Migrations} --project {projectName}

Adding an EF Core migration in a different project than your main one? 🔗

Real-life applications are usually split into different projects. We usually want to keep the domain objects separate from the web application. You will have multiple ‘whatever’ layers that will make the separation clearer for the teams.

Make sure you navigate to your MyApp.Domain CLI and run the commands from there

dotnet ef migrations add MyMigration --output-dir ../MyApp.Domain/Migrations --startup-project ../MyApp.Web --verbose

Otherwise, you will end up with a big error like the one below.

Y_our target project 'MyApp.Web' doesn't match your migrations assembly 'MyApp.Domain'. Either change your target project or change your migrations assembly.
Change your migrations assembly by using DbContextOptionsBuilder. E.g. options.UseSqlServer(connection, b => b.MigrationsAssembly("MyApp.Web")). By default, the migrations assembly is the assembly containing the DbContext.
Change your target project to the migrations project by using the Package Manager Console's Default project drop-down list, or by executing "dotnet ef" from the directory containing the migrations project._

To fix that, you will need to specify in Startup.cs the assembly for the migrations.

services.AddDbContext<TechEventContext\>(options \=>
  {
      options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection"),
          m \=> m.MigrationsAssembly("MyApp.Domain"));
  });

Once you did this, you need to run the command again. If successful, you will have the new migration file added to your MyApp.Domain project, under the Migrations folder.

Configuring a custom domain in Azure

2019-11-03T00:00:00Z

Configuring a custom domain in Azure very easy, if you know what to configure. There are domain bindings, TXT records, A records, and we don't deal with them on a daily basis.

Your AppService plan must be at least B1, to allow custom domains and SSL bindings.

Once you have your application deployed, you must create a DNS Zone that will allow you to link your existing custom domain to your AppService.

So in order for your website to work in every situation, with your custom domain, you will need to add 4 record sets:

an A record type with www as the name and your website assigned IP as a value
an A record type with @ as name and your website assigned IP as the value(this will be already created, but make sure is there)
a TXT record type with www as a name and [yourwebsite] .azurewebsites.net as the value
a TXT record type with @ as a name and [yourwebsite].azurewebsites.net as the value

Adding an A record 🔗

Adding a TXT record set 🔗

You need to have these 4 records in order to allow your website to be accessible with www, and without it. Like coolwebsite.com vs www.coolwebsite.com.

In my case, my website couldn't be accessed from a few corporate networks. Unfortunately, it took a while until I realized what is happening.

I tend to access websites without using www in front of the domain. It's easier to write, and Google Chrome has the tendency to suggest pages :)

There are a few firewalls or corporate networks that will prevent your website from being loaded if the DNS is not resolved for both options, and you might not even know it

DNS propagation might take a while, but you can use tools like
https://www.whatsmydns.net/ .

Using this application you can select any record you want to check to make sure it is propagated.

Web API template in Asp Core 3.0

2019-10-01T00:00:00Z

Asp Core 3.0 comes with a lot of interesting things in terms of functionality (gRPC, WorkerServices, Identity, a little Blazor), but also with template changes.

One of these changes is the template for Web API, which suffered a small and good transformation.

As soon as the project was created…I was surprised to see the WeatherForecast.cs file. I though...”Oh…I might have chosen the wrong project type”.

But no, .Net Core team decided that there is time to get rid of that ValuesController that had pretty much no significance. Indeed it had ‘REST-ish” structure and it returned some data but that was it.

The new Web Api project comes with a few changes.

Has a default model named WeatherForecast.cs
The ValuesController is replaced by WeatherForecastController - to be honest, I never liked the dummy strings returned by GET action, and now at least the values are more human-friendly and in a way, bring you closer to Blazor :)
A Logger is already injected in the controller, making it more visible at the platform level
A list of randomized model properties is returned instead of 'value1', 'value2' in previous versions

The new controller has only the action that responds to GET requests and returns an IEnumerable.

private static readonly string[] Summaries = new[] { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" };

In terms of controller actions:

Title

[HttpGet]
     public IEnumerable<WeatherForecast> Get()
     {
         var rng = new Random();
         return Enumerable.Range(1, 5).Select(index => new WeatherForecast
         {
             Date = DateTime.Now.AddDays(index),
             TemperatureC = rng.Next(\-20, 55),
             Summary = Summaries[rng.Next(Summaries.Length)]
         })

In Startup.cs you will see a lot of new things:

public class Startup
  {
      public Startup(IConfiguration configuration)
      {
          Configuration \= configuration;
      }

      public IConfiguration Configuration { get; }

      // This method gets called by the runtime. Use this method to add services to the container.
      public void ConfigureServices(IServiceCollection services)
      {
          services.AddControllers();
      }

      // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
      public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
      {
          if (env.IsDevelopment())
          {
              app.UseDeveloperExceptionPage();
          }

          app.UseRouting();

          app.UseAuthorization();

          app.UseEndpoints(endpoints \=>
          {
              endpoints.MapControllers();
          });
      }
  }

Unlike previous versions, you won't see the UseMvc() extension method in
ConfigureServices in Startup.cs, which added the conventions necessary for routing( as we were used to from MVC).
Now this is replaced by a call to AddControllers(), which as the name implies will add only the controller part needed in a Web Api Project.

There are several options in
MvcServiceCollectionExtensions class: AddMvc(), AddControllersWithViews() or AddRazorPages()

app.UseEndpoints() is a new extension of IApplicationBuilder that dispatches requests. More than that, the configuration part of an endpoint has been moved here from app.UseRouting().
The configuration endpoints.MapControllers(); maps attribute routing controller.

These are not major changes, and I personally enjoy how the .NET team is doing their best to make everything as configurable and performant as they can.

Worker Service in .Net Core 3.0

2019-08-01T00:00:00Z

What is a Worker Service, what is solves? 🔗

Sometimes our business scenarios need long-running tasks that run in the background, to watch something or compute something.

This kind of scenario was impossible before .Net Core 2.1. A lot of functionalities were 'ported' or re-written from the old version, but this wasn't included.

In the old .Net full-framework, we use to implement long-running tasks as Windows services. We delivered them in production not without a lot of hassle.

When .Net Core appeared, it promised to be not only faster, smaller, performant but also cross-platform.

It opened a whole new world to .Net developers, it allowed us to change hosting environments as we pleased but it didn't provide us the whole ecosystem that we had in .Net full-framework.

Building background-services was impossible until a later version of .Net.

With .Net core 2.1 release, there was an option to have a self-hosting service inside your web app by implementing IHostedService interface. Later on, they introduced the concept of BackgroundService that you could customize.

Worker Services become a first-class citizen in .Net Core 3.0. Visual Studio 2019 has a template for it. It was bringing back the concept of ‘service’ as we used to know in .Net full-framework.

Visual Studio 2019 Project template

The generated project is composed of 2 classes and an appsettings.json which is more than enough to get started.

The generated project

Worker Service Implementation 🔗

At its basis, it’s nothing more than a small and smart console app that has a built-in DI container.

public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureServices((hostContext, services) => { services.AddHostedService<Worker>(); });

This will allow you to register all the dependencies (repositories, business services, external libs) that will be used in your Worker, just as you do in Web API or MVC.

The base class BackgroundService – was built to provide a way of running long-running tasks in the background under .Net Core. A Worker is exactly that - a long-running, background task.

The Worker.cs class is everything you need to implement your functionality. You can control what to run and when to run in ExecuteAsync method.

public class Worker : BackgroundService { private readonly ILogger<Worker> _logger;

public Worker(ILogger<Worker> logger) { _logger = logger; }

protected override async Task ExecuteAsync(CancellationToken stoppingToken) { while (!stoppingToken.IsCancellationRequested) { _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now); await Task.Delay(1000, stoppingToken); } } }

Having the new Worker Service in .Net Core will allow us to cover different business scenarios. Polling a service, running a specific task at a specific time will be very easy.

GraphQL to the rescue - a short introduction

2019-04-09T00:00:00Z

GraphQL is a query language invented by Facebook and exposed to the public in 2015. Is an open specification that allows you to query APIs in a flexible and intuitive way.

We keep hearing about GraphQL and how it introduces a revolution in the way you are writing apps, and how GraphQL is better than REST or how it is REST 2.0. It’s not about being better, it’s about solving some flaws REST has, and complementing REST.

Most of us, when we’re talking about APIs, we’re referring to REST APIs, or at least wannabe REST APIs.

A short summary of REST constraints 🔗

Client – Server – it assumes the existence of a client and a server, and the server should not be aware of the client’s existence
Stateless – the server keeps no trace, no identifier at all, and if there is a trace, that is contained in the request. The server treats every request as a new one, having no history
Cache

Caching is one of the most important specification of the HTTP RFC. With that it can allow a client to make as many requests as needed, but the server will not necessarily make the trip to the database to bring the same data.

4. Layered system – the client doesn’t know if it talks with a proxy or a load balancer, as long as the response is received, and it shouldn’t care

5. Uniform resource

Has 4 sub-constraints

Identification of resources – each resource should be identifiable and addressable
Manipulation of resources through representations – a client will never interact with a database resource, it most likely interact with a representation of a resource. That representation might be a composed representation, or a sub-representation of, for example a database entity
Self-descriptive messages – Each request/response should contain everything necessary so that each party can be able to understand it correctly. It should contain the right HTTP Method (in the intended usage way), the correct Status Code and the right headers (for example Accept, Content-Type, or any custom header)
HATEOAS – hypermedia as engine of application state

Assumes that the next step the clients will be able to perform will be contained in the response as a separate area.

{ "links": { "self": { "href": "/speakers" },
"next": { "href": "/speakers?page=2" }
} }

In other words, Roy Fielding argues that a client shouldn’t know anything about the API, except its initial URI and the appropriate media-types and verbs. This way the server will be able to understand what is asked and respond accordingly if the client includes all the necessary info in the request.

From that point on, all the application state transitions will be driven by the client-selection of the received representations from the server, or from the user’s manipulation of them.

REST, as an architectural style is very powerful, and it aims to treat everything as a perfectly addressable resource, leveraging the correct response codes, the correct HTTP Verbs and HTTP headers, while maintaining no trace whatsoever about previous request.

It aims to allow a server and a client to evolve independently and to allow the server to drive the application state by leveraging HATEOAS and hypermedia types.

Unfortunately, a good number of the APIs out there, completely ignore the HATEOAS part - under the pretext that it adds overhead to each response or that there’s no real benefit in adding it.

It might be true in some scenarios, but it also brings a lot of power if implemented correctly and it’s up to your design, to do it or not.

Issues with REST APIs 🔗

REST APIs even with their demonstrated results, tend to have 2 major problems.

Overfetching – we struggle to be so compliant to REST and most part of the data that is transferred over the network ends up being ignored and not displayed in the UI, and it gets thrown.
Underfetching – comes hand in hand with overfetching, and is happening when the consumer is forced to make another call to an endpoint to bring other data

Some say that overfetching is bad design, or lack of interest, and it can be avoided. It can, but you don’t always have control over the consumer app.

As soon as you expose your API to the public - to be consumed by third parties, or if the client application is developed somewhere else you pretty much lost the control over your API’s design.

You won’t be able to tell what data they use from your responses if they use just a field, or two fields, or the entire response.

While you can do everything to expose a performant API, you can’t customize it for every possible scenario, and for any potential customer or consumer app.

GraphQL to the rescue 🔗

With GraphQL, you’ll be able to model the data you expose in a way that is very similar to a graph. You’ll have nodes of related data, that can be ‘navigated’ by your consumers.

query { talks{ description title feedbacks{ comments delivery } speakers{ companyName position } } }

This kind of request is very intuitive, and the response to such query will bring over the network only the requested data, therefore giving a lot of flexibility to potential consumers.

GraphQL allows your consumer to manipulate hierarchical data and to create queries and mutations on the fly, in the way that you define it on the server side.

One of the scenarios where GraphQL might prove its power is along with a microservices architecture.

For this, you could create a gateway-like API that will aggregate data from several APIs and, in turn will expose queries and mutations to the client apps.

This way you can allow your consumers to get only the data they need, but a degree of nesting that you see fit, all with a single call to the server.

No more subsequent calls to different endpoints, no more endpoint chaining hell, and no more endpoints! You’ll have only one endpoint used by any consumer might be out there.

Think about this as if you would like to separate the stones from the sand, and you sift the very fine sand.

What can you do with GraphQL 🔗

Queries in GraphQL 🔗

A query in GraphQL is pretty much everything that can be ‘questioned’ from the outside, allowing the consumer to specify what data it needs to be returned from the API.

Queries can be executed in in parallel, on the same call.

query { talk(id: 1) { description title speaker{ lastName } }

Mutations in GraphQL 🔗

A mutation in GraphQL is pretty much everything that changes a certain state. A POST, PUT, DELETE request, that modifies something.

Mutations will be executed sequentially, not in parallel.

mutation($talk: talkInput!) { createTalk(talkInput: $talk) { title description speakerId } }

Downsides of GraphQL 🔗

Although, you can’t say that GraphQL is better than REST - because these are 2 different concepts, for sure you can leverage both to get the most of your APIs, but you need to be aware of the flaws - Caching

Caching is one of the most important specification of the HTTP. We use it to improve performance, to save a trip from the web server to the database server, and we use it to trick the user that everything runs very fast.

When we’re talking about GraphQL, you’ll have a single URL where you get your data from, but that request can be made with different bodies or parameters.

Facebook started the hype, and now GitHub announced that the v4 of their API will be fully on GraphQL.

I mean, why would they do that if they can’t cache responses to improved perceived performance?

Well, they have so many clients, and so many endpoints, that it really makes sense for them to switch to GraphQL and to give their consumers the needed flexibility. In the end, they can’t tell for sure what data they use from the responses.

Simply because these giant use GraphQL, it doesn’t mean you should use it too.

You need analyze what are your scenarios, the pro and cons, and to know exactly what’s the end goal for you. You want to just use it, you want the flexibility of it, are you willing to sacrifice caching to flexibility? Don’t just use it without a real reason.

Getting started with git

2019-01-24T00:00:00Z

Sometimes, git usage might be a little bit overwhelming for those that are just starting to learn programming.

It's not a bit deal to use git, but I remember that even for me wasn't so easy. We're so comfortable with Visual Studio that the first thing that comes in mind is to install a little extension and to use git from there.

It would surely work, but once we try the command line, we're not going to use git in visual studio.

After watching this video you'll be able to:
- create a new repository
- add code
- commit changes in your repository
-update existing code

Here's a little intro that might prove useful.

Enjoy!