But once you move beyond basic apps, CRUD starts to fall apart.

Real-world systems don’t just “update” or “delete” things. In a loan application system, for example, borrowers “submit” applications, loan officers “approve” or “reject” them, and applications are eventually “archived”. These aren’t generic CRUD operations—they’re domain-specific actions that carry meaning.

And that’s the problem: CRUD hides the meaning of our systems behind vague verbs. REST APIs inherit the same issue, mapping HTTP verbs onto CRUD but still failing to express real workflows clearly.

In this article, we’ll explore:

• Why CRUD works fine for simple apps but becomes an anti-pattern at scale

• How concepts like upsert, archive, and bulk operations reveal its cracks

• Why REST doesn’t solve these issues

• How to design APIs around domain actions and workflows instead.

By the end, you’ll see CRUD for what it really is—a teaching tool, not a design philosophy.

Table of Contents

• What is CRUD?

• Stretching CRUD: Upsert, Archive, Bulk

• Breaking CRUD: Domain Actions

• Breaking CRUD: Domain Authorization

• CRUD Alternative: Align to Workflows

• Conclusion

What is CRUD?

Create, Read, Update, Delete—these are the four basic operations we perform on data in a database.

• Create – adds a new record.

• Read – fetches an existing record (or list of records).

• Update – changes one or more fields in a record.

• Delete – removes a record.

For example, in a typical Node.js + Express app managing users:

// Create a user
app.post('/users', createUser);

// Read a user
app.get('/users/:id', getUser);

// Update a user
app.put('/users/:id', updateUser);

// Delete a user
app.delete('/users/:id', deleteUser);

This maps directly to the underlying SQL:

INSERT INTO users (...);
SELECT * FROM users WHERE id = ...;
UPDATE users SET ... WHERE id = ...;
DELETE FROM users WHERE id = ...;

And that’s CRUD in its purest form—four operations that can describe almost any database interaction.

Stretching CRUD: Upsert, Archive, Bulk

Developers quickly realize CRUD isn’t enough, so they invent extensions:

• Upsert: a mix of “update” and “insert.” If the record exists, update it; if not, create it.

• Archive: instead of deleting a record, we “soft delete” or mark it as inactive so the history stays intact.

• Bulk operations: run create, update, or delete on many records at once for efficiency.

These solve real problems, but they stretch CRUD’s simple model. We now need to distinguish between single and bulk resource actions. And we also need to factor in the technical concerns of upsertions and soft deletions.

Breaking CRUD: Domain Actions

The technical domain itself stretches CRUD substantially, but business domain concerns break it entirely. Take a loan application system:

• A borrower doesn’t “create” and “update” an application—they start, submit, or withdraw it.

• A loan officer doesn’t “update” an application—they review, approve, or reject it.

• Applications don’t get “deleted”—they’re usually archived so there’s a record for compliance.

If we try to model these as plain CRUD, the meaning gets lost:

PATCH /applications/123 { "status": "approved" }

Technically, it works. But what does “update” really mean here? Was the application submitted, rejected, or archived? You can’t tell from the API call.

The core problem: CRUD hides intent behind generic, technical language. Real business processes are expressed as domain-specific actions, not generic updates or deletes.

Breaking CRUD: Domain Authorization

CRUD not only obscures intent—it also creates authorization gaps. Using the same loan application example:

• Only loan officers should approve applications.

• Borrowers should only edit their own information or withdraw their applications.

If “approve” is just modeled as a generic update, the system can’t distinguish between roles without additional checks. A naive authorization rule like “can this user update?” suddenly lets borrowers perform actions reserved for officers.

This mismatch between technical verbs and business rules can lead to:

• Security issues—unauthorized actions performed by the wrong user.

• Audit problems—it’s unclear who did what, and when.

• Workflow confusion—state transitions get lost in generic updates.

The solution: treat each domain action as its own API call with explicit authorization rules:

POST /applications/123/approve   # Only accessible to loan officers
POST /applications/123/withdraw  # Only accessible to the borrower

By modeling actions instead of CRUD operations, intent and permissions are clear, reducing both bugs and security risks.

CRUD Alternative: Align to Workflows

Real-world applications follow workflows—sequences of states that a resource moves through. Take our loan application example:

Here’s what the corresponding API endpoints might look like:

# Borrower actions
POST /applications/123/submit       # Draft → Submitted
POST /applications/123/withdraw     # Draft/Submitted → Closed

# Loan officer actions
POST /applications/123/approve      # Submitted → Approved
POST /applications/123/reject       # Submitted → Rejected

# System/Admin actions
POST /applications/123/close        # Approved/Rejected → Closed

# Side effect: spawning a Loan (after Approved)
POST /loans
{
  "applicationId": "123",
  "amount": 50000,
  "borrowerId": "456",
  "terms": { ... }
}

At this point, our API calls are almost entirely outside the CRUD pattern—the only one that resembles a CRUD action is the spawning of a loan, which looks like a “create”. Behind the scenes, we’ll still use INSERT, SELECT, and UPDATE statements in SQL, but at the API level we’re aligning to the actual business workflow. Because of it, we’re able to easily support the following:

1. Actions reflect business intent — each API call maps to a real-world task like submit, approve, or withdraw.

2. Built-in authorization — endpoints clearly separate borrower, loan officer, and admin responsibilities.

3. Auditability and workflow enforcement — state transitions are explicit and invalid transitions are prevented.

4. Controlled side effects — spawning loans, notifications, and downstream processes are handled deliberately.

Conclusion

By moving away from CRUD and modeling domain actions instead, our API aligns with real business workflows, clearly communicates intent, and enforces rules and authorization naturally. State transitions, side effects, and auditing become explicit, reducing errors and security risks. While CRUD still powers the underlying database operations, thinking in terms of actions and workflows ensures that the system behaves the way the business expects.

Now I find myself designing event schemas for sending messages across a distributed system. It's a very similar problem with similar pain points and solutions. Adhering to data contracts is critical to ensure we don't frustrate event subscribers or bring down systems.

Versioning APIs is translatable to versioning event schemas, but if you can effectively evolve schemas, you don't actually need versioning. Effective evolution of schemas comes down to avoiding breaking changes.

Though I covered that briefly in the article above, here I want to thoroughly address breaking changes and propose more solutions to avoiding them.

What are Breaking Changes?

Essentially, a breaking change to a schema (in an API or event context) is anything that requires a consumer to make an update on their end. It's a change that forces change. Schemas will evolve, but once a schema is in use in production, you have to be very careful not to break the data contract.

Removing an event format or changing an event's basic structure constitutes a breaking change. But the nuts and bolts are at the attribute (the field or property) level.

Structural breaking changes

Here's a list of structural breaking changes for schema attributes:

• Renaming Attributes – Changes to an attribute's name, even if it's just changing the case (for example, from camelCase to TitleCase), is a breaking change.
• Removing Attributes – Taking an attribute out of a schema.
• Data Types Changes – Changing data types, even if the change seems compatible.
• Making Attributes Required – Anytime you mark an attribute (even a new one) as required when it wasn't before, it's a breaking change.

Semantic breaking changes

The other primary category of attribute-level breaking changes has to do with changes in what the data means, or semantic changes. They force consumers to re-interpret the data they're getting.

They are as follows:

• Format Changes – Any change to the format of an attribute.
• Meaning Changes – When the declared or implied meaning of data changes.
• Stricter Constraints – When attribute requirements are added or made more restrictive.

It's important to note that what counts as a "breaking change" might be more nuanced. Changing an amount from dollars to cents still forces a change by event subscribers, in interpreting the meaning of the data being sent. Be careful of those, as they are not always obvious.

What are Non-Breaking Changes?

We can generally describe non-breaking changes as additive or permissive ones. These are changes that don't require change for consumers.

Here is a list of non-breaking attribute changes:

• Adding New Attribute – In all schema contexts, the addition of a new attribute is a non-breaking change, so long as it's not required (for example, for a POST request).
• Making Attribute Not Required – When an attribute was required but newer schema versions do not require it.
• Looser Constraints – Things like more permissive integer ranges (min and max) or allowing for greater decimal precision. Be cautious and communicate with consumers, though, as they may rely on stricter constraints.

Non-breaking changes can often be avoided. But evolving schemas effectively can be challenging and require a lot of thought so as not to break schemas and consumers' trust.

How to Evolve Schemas

Sadly, the list of breaking changes is longer than the non-breaking ones. But there are some strategies for evolving schemas in a non-breaking way.

1. Domain Knowledge – Understanding the domain will help ensure you don't end up with poorly named attributes, attributes on the wrong object, or incorrect data types.
2. Specific Attribute Names – Rather than changing an attribute's name, data type, or format, introduce a new attribute with a more specific name and correct the data type or format.
3. Attribute Names With Intent – Leverage attribute names that reflect their format or intent. For example, consumers might not know whether providerCost would be in dollars or cents, so specify with providerCostInDollars or providerCostInCents. This will also prevent a breaking change if you're having calculation precision issues with dollars and decide to deliver the cost in cents.
4. Drafted Schemas & Attributes – Utilize "draft mode" extensively at the schema level, getting feedback on attributes in simulated environments before they are live in production. For schemas that are in use in production, you could introduce a draftedAttributes object and dump experimental (non-production ready) attributes into it. Communicate with consumers that they attributes are being refined – so they should expect breaking changes – and will be moved to the main schema when ready.
5. Support Existing Attributes – Leave old attributes in the schema. Don't remove old attributes unless you've been able to coordinate a deprecation/sunsetting strategy with consumers.
6. Versioning – If necessary, version your schemas. Although it can become quite difficult to maintain, versioning your schemas is a way to allow for backwards compatibility but move forward with a new schema. You can do high-level versioning (for example, v1 and v2) or more granular semantic versioning (for example, v1.0.1). It's best to version each schema independently, so you don't have to, for example, copy all API v1 endpoints to v2.

Conclusion

Breaking changes are a quick way to break trust for any API consumers or event subscribers. I hope that the guidelines above will provide more insight what constitutes a breaking versus non-breaking change, and how to evolve schemas effectively.

If you can't avoid breaking changes, make sure to coordinate with any and all consumers. You can actually earn more trust with your consumers if you effectively evolve schemas and communicate breaking changes when they are necessary.

Copilot offers a variety of AI tools that have radically streamlined my experience as a software developer. I've used it to generate code, tests, and even simple applications. It's also great for debugging, refactoring, and documenting existing code.

Weirdly, using Copilot has caused me to develop features faster than business stakeholders can review them.

It's important to note that AI tools, including Copilot, can be blatantly wrong, apologize (or not) when corrected, and then confidently produce the same error. But as long as you're aware of the downsides of AI tools, and have enough coding knowledge to recognize when they're incorrect, you can mitigate them on the path to substantially improved productivity.

How to Setup GitHub Copilot

For setup and basic usage of Copilot, check out the docs. You can add on Copilot to an individual or business account, and there's a free trial and reasonable pricing after the trial.

After adding Copilot to your GitHub account, you'll want to install the plugins for your IDE and log into GitHub to access Copilot.

In this article, we'll use these Visual Studio Code extensions:

Notes:

1. This info is up-to-date as the writing of this article, but will likely change as GitHub evolves these products.
2. I haven't yet received access to Copilot Voice or Copilot (X) for Pull Requests, so my perspective on these are limited and based on GitHub's preview docs.

Privacy

Before jumping into some key use cases for Copilot, a quick note on privacy: Basically, if you trust GitHub to host your source code, you can likely trust what they do with your Copilot prompts and code snippets. [See their FAQ docs and Privacy Statement.]

Use Cases for GitHub Copilot

The uses cases for GitHub Copilot are numerous, especially when you add in the preview features of Labs, Chat, and Voice. Using Copilot's features can really streamline the development process.

Here are some great ways to leverage Copilot extensions:

Code Generation

Copilot is known for its code completion features. If it's given a comment in the code or you type the beginnings of a line of code, Copilot will suggest a solution that you can accept, ignore, or explore alternatives. It's referred to as "ghost text".

Once you have the Copilot extension installed and you're logged in, code completion is as simple as typing instructions and hitting the Tab key once the suggestion comes up.

A comment prompt in Ruby that Copilot uses to create a method and invocation

Taking code completion one step further, Copilot Chat can take a single prompt and generate instructions for building an entire application.

I asked it to create a REST API in Node with CRUD functions for "products", and it generated functional code. Impressive overall. Given the same prompt, ChatGPT also gave me instructions for how to run the code, which was nice.

Copilot Voice can also write or edit code based on voice commands. Most of the time, using the keyboard with Copilot code completion is faster than dictating lines of code with Voice. But it's compelling to think about using Copilot Voice to create and run code without having to type or stare at a screen.

Explaining Code

I often have to stare at a screen to figure out what a block of code is doing. Sometimes it's legacy code where I don't understand the business context. Sometimes it's using a particular library I'm not used to. Sometimes I curse the person who wrote it, even if it's me.

Below is some code generated by Copilot Chat from my "REST API in Node..." prompt from above:

app.get('/products/:id', (req, res) => {
  const id = req.params.id;
  const product = products.find((p) => p.id === id);
  if (product) {
    res.json(product);
  } else {
    res.status(404).json({ error: 'Product not found' });
  }
});

I took this code and fed it into the "Explain" feature in Copilot Labs. Here's the response...

Here is the explanation for the code above:

1. We define a route with the route path /products/:id. The colon : in the path indicates that it is a route parameter. The value of the route parameter will be available in req.params. For example, if the route path is /products/:id and we make a request to /products/5, then the value of req.params will be { id: 5 }.
2. We get the id from req.params and find the product with the given id from the products array. If a product with the given id exists, we return it. Otherwise, we send a 404 error response with the error message Product not found.

This is a pretty straightforward segment of code, and the response is clear and straightforward as well. It would be easy to add this as documentation in a code comment above the function.

Another good example is regular expressions. I understand how regular expressions work but I don't often have the patience to figure out what a particular regex is doing. I fed Copilot Chat this giant regex statement for email validation:

(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])

It explained the regex at a high level, indicating it was broken into the local and domain parts, representing before and after the "@" sign in an email address. Then it described allowable characters in each part. Quite helpful.

Language Translation

Developers are often required to quickly learn new languages and frameworks. Copilot Labs and Chat make this pretty easy. Here's an array of products in JavaScript and Ruby that was converted by Copilot:

let products = [
  { id: '1', name: 'Product 1', price: 10.99 },
  { id: '2', name: 'Product 2', price: 19.99 },
  { id: '3', name: 'Product 3', price: 7.99 }
];

products = [
  { id: '1', name: 'Product 1', price: 10.99 },
  { id: '2', name: 'Product 2', price: 19.99 },
  { id: '3', name: 'Product 3', price: 7.99 }
]

This is a very simple example, so let's try making this into a class and going the other way (from Ruby to JavaScript):

class Product
  attr_reader :name, :price

  def initialize(name, price)
    @name = name
    @price = price
  end
end

class Product {
  constructor(name, price) {
    this.name = name;
    this.price = price;
  }
}

This checks out. For good measure, I tested TypeScript as well, and it worked perfectly, too.

Debugging

This is a very handy feature. You can give Copilot Chat or Labs problematic code or error messages and it will indicate what it thinks the issue is.

Copilot Labs "Fix Bug" Brush Feature

I can't tell you how many hairs I've pulled out because I couldn't find what amounted to a syntax error. Copilot's ability to fix bugs just makes me happier and hairier.

You can also give Copilot Chat an error message with no other prompt and it can tell you the issue. I arbitrarily removed a dot from the Node REST API code:

products[productIndex] = { id, ..req.body };

I copied/pasted the error message in Chat, and it responded with...

Looking at the code excerpt you provided, it seems that the issue is on line 49 where there is a syntax error in the object literal. The ".." before req.body is causing the error. It should be just one dot instead of two.

This is both correct (the line and source of the error) and incorrect (that it should be only one dot). It then gave me a code snippet with three dots, which is also correct.

As I mentioned at the outset, you've gotta double-check AI's work. Still, I'm impressed by Copilot's ability to parse an error message, describe what it thinks is wrong, and suggest a fix.

Refactoring

Another great use case is refactoring. Consider the code below:

def price_with_discount
  price - (price * discount_rate)
end

This simple price calculation doesn't factor in nil values, strings that should be numbers, or reasonable values for price or discount_rate. We need the code to do this:

1. Ensure price is an integer or float (not nil)
2. Ensure price is not negative
3. Ensure discount_rate is a float (not nil)
4. Ensure discount_rate is not negative and less than or equal to 1

Copilot Chat handles this with ease...

def price_with_discount(price, discount_rate)
  raise ArgumentError, "Price must be a positive number" unless price.is_a?(Numeric) && price >= 0
  raise ArgumentError, "Discount rate must be a float between 0 and 1" unless discount_rate.is_a?(Float) && discount_rate >= 0 && discount_rate <= 1

  price - (price * discount_rate)
end

Test Generation

Using Copilot to generate tests is technically a subset of "Code Generation" above, but I felt it was so useful it warranted its own mention.

Generating unit tests for code can be tedious if you're trying to cover happy and sad paths, primary use cases and edge cases. Our price_with_discount code above needs test cases to ensure an error is raised if price or discount_rate don't meet the requirements. In addition, we might want to test the following:

1. A price without a discount_rate
2. A price with a reasonable discount_rate (for example, a 10% discount)
3. A price with a 100% discount_rate (for example, if we want to give the product away)

With these and our previous error cases, here's what Copilot Chat generated, after a little fine-tuning (re-prompting) and switching from Minitest to Rspec.

RSpec.describe Product do
  describe "#price_with_discount" do
    context "when given a valid price and discount rate" do
      it "returns the price with the discount applied" do
        product = Product.new("Test Product", 100, 0.2)
        expect(product.price_with_discount(product.price, product.discount_rate)).to eq(80)
      end
    end

    context "when given a nil price" do
      it "raises an ArgumentError with an appropriate message" do
        product = Product.new("Test Product", nil, 0.2)
        expect { product.price_with_discount(product.price, product.discount_rate) }.to raise_error(ArgumentError, "Price must be a positive number")
      end
    end

    context "when given a price less than 0" do
      it "raises an ArgumentError with an appropriate message" do
        product = Product.new("Test Product", -100, 0.2)
        expect { product.price_with_discount(product.price, product.discount_rate) }.to raise_error(ArgumentError, "Price must be a positive number")
      end
    end

    context "when given a nil discount rate" do
      it "raises an ArgumentError with an appropriate message" do
        product = Product.new("Test Product", 100, nil)
        expect { product.price_with_discount(product.price, product.discount_rate) }.to raise_error(ArgumentError, "Discount rate must be a float between 0 and 1")
      end
    end

    context "when given a discount rate less than 0" do
      it "raises an ArgumentError with an appropriate message" do
        product = Product.new("Test Product", 100, -0.2)
        expect { product.price_with_discount(product.price, product.discount_rate) }.to raise_error(ArgumentError, "Discount rate must be a float between 0 and 1")
      end
    end

    context "when given a discount rate greater than 1" do
      it "raises an ArgumentError with an appropriate message" do
        product = Product.new("Test Product", 100, 1.5)
        expect { product.price_with_discount(product.price, product.discount_rate) }.to raise_error(ArgumentError, "Discount rate must be a float between 0 and 1")
      end
    end
  end
end

One test for valid input, five for invalid input. All six work, and I didn't have to write them!

Code Reviews

One feature of Copilot X is Copilot for Pull Requests. Here are some of the key features:

• Template Expansion – Leverage Copilot to fill in your PR template and explain code
• Gentest – Generate tests for your code based on Copilot's analysis
• Ghost Text – Receive suggestions while you're typing in the PR

Voice-Driven Development

Formerly known as "Hey, Github!", Copilot Voice allows you to use natural language prompts to interact with your code. It looks impressive, boasting these capabilities:

• Write/Edit Code – Use voice controls to trigger Copilot code suggestions
• Code Navigation – Navigate a file without a keyboard or mouse
• Control the IDE – Trigger any VS Code command
• Code Summarization – Get summaries of blocks of code

Summary

GitHub is rapidly producing revolutionary developer productivity tools with its suite of Copilot extensions. It's increasing my joy in programming and decreasing my time spent on mind-numbing tasks. I would encourage you to keep track of enhancements to Copilot as they're happening quickly.

Ignore click-bait promises of a "10x productivity gain", but don't ignore the research of Copilot's impact on developer productivity and happiness.

Spend some time with Copilot tools trying out the use cases above, and I think you'll be surprised by its effect on your productivity and happiness.

Some people go for cake and ice cream. Others plan a fun outing. I got an outage instead of an outing. And it was anything but fun.

In the midst of it, my colleague and I vacillated between triaging the issue and fuming about how difficult it was to find its source.

And as I came up for air to connect with my patient and insightful wife, I shared with her how inadequate I felt, and consulted with her in how to communicate effectively with the affected client.

They needed to know we were going to fix it. They needed that fix to be fast. They needed to know the fix would last.

We tactfully crafted emails and had reassuring phone calls with them. We updated them often and gave them the right amount of transparency and technical insight.

But here are the truths that we couldn't tell them.

1. We were not prepared for this

As is the case with many engineers on many projects, we inherited this application. We were left with little documentation and poor tools for debugging production. And there are too many moving parts to count.

It's like we're taking a fire extinguisher into a forest fire.

Our time and your financial budget didn't allow for extensive preparations for a production outage, and now we're facing the heat. In more ways than one, we were not prepared for this.

2. The cause of the outage could be one of 20 things

The cause? Might be the server. Might be the code. Might be the database or a third-party package. Might be food poisoning. Might be our fault. Might be yours.

The solution? Might just need a restart. Might need an index on that database table. Might need to update that package or configuration setting. Might need Pepto-Bismol. Might need to burn the whole thing and start again.

3. We have absolutely no idea how long it's going to take to fix

A restart of the server could take ten minutes. A rebuild of the server could take anywhere from ten hours to ten days. We might be able to track down the bug in a few minutes, or we may never discover what actually happened.

It all depends on identifying the cause, and we've already established that could be one of 20 (or more) things.

We've also established that we weren't prepared for this. Might as well leave us alone and trust that we care enough to fix the problem as fast as possible.

In the meantime, we'd suggest you considering reworking your definition of "fast".

4. We need the problem to manifest again before we can figure out the cause

Because we have so little in the way of tools and documentation, we're basically flying blind. Thankfully, we've installed some monitoring tools to help us out.

The catch is that those tools can only monitor things going forward. So we need this intermittent issue to show up again before we can actually diagnose the problem.

We could certainly try this in a staging or test environment, and we did, but it's not succumbing to the same problems that production is experiencing. And, actually, it's an entirely different setup than production.

Our only option at this point is to take down production again. Tell your team to hold on tight while we pound production, not to try to fix it, but just to reproduce the problem so our tools can capture what's happening.

5. You really should be paying us more for this level of stress

We're not sleeping. Barely eating. Our families haven't seen us for days. We spend all our time in front of a computer except for short bursts in front of the refrigerator, in the bathroom, or in the corner in the fetal position.

These stress levels warrant double pay, at least. But we realize now is not the time to negotiate a new contract. We're all in survival mode, and apparently, production's health is more important than our own.

And that's the reason why you should pay us (a lot) more during an emergency outage.

Concluding Thoughts

These are truths that engineers really can't communicate to their clients during the crisis of a production outage.

If you've thought some of these things, just know that many of us have thought them. If you resonate with these sentiments, many of us have felt this way. Production outages cause immense amounts of pressure and stress.

If you're wondering about the actual circumstances of my birthday outage, the issue was an intermittently unexpected response from a third-party email service. It caused an application error, but that error wasn't caught.

Instead, the request was tried again. And again. And then a few hundred (thousand?) more times until it brought the server to its knees. We'd restart the server and within another hour it was down again.

It took days to track down the actual cause, as our monitoring and debugging tools weren't honed. We saw spiked CPU and RAM usage but no clear link to rogue processes. We couldn't reproduce the problem in any environment but production. And the offending code was abstract and utilized libraries we weren't familiar with.

Next time, we'll be more prepared. We've installed tools to give us profiling capability and stack tracing for requests in production. We're going to be more cautious in implementing third-party tools and ensure our application can gracefully handle their failure.

I, personally, plan to negotiate a higher rate (likely 1.5 or 2 times my normal rate) for outages that make me drop all my other responsibilities.

Our preparation should also include a commitment to staying calm and silencing doubt. Panicking causes us to chase symptoms instead of focusing in on the source. Doubt tries to convince us we can't figure out the problem and never will be able to.

Operating out of a place of calm and confidence will bring that needed reassurance to our clients, and help us effectively navigate production outages. And have more fun on our birthdays.

If you've been burned by API changes, you're probably the one fussing. If you are a maintainer of an API, you might also be fussing about trying to field challenging questions like these:

# Is this version 2 of just products or of the entire API?
/v2/products

# What catalyzed the change between v1 and v2? How are they different?
/v1/products
/v2/products

These questions around versioning are not easy to answer. It's not always clear as to what v1 or v2 is referring to. And we should not just make a second version of an endpoint when the first no longer seems to suffice.

There are clear reasons why your API needs to have versioning, and there are clear strategies for how to effectively navigate API changes.

However, I have found that most developers--including myself, until I learned some lessons the hard way--are not aware of these reasons and strategies.

This article seeks to highlight those reasons for versioning and strategies for accomplishing it. We're going to assume a REST API context, as it's a standard for many APIs, and focus on the versioning aspect.

What is Versioning?

We should start with level-setting on what is meant by the term "API versioning". Here's our working definition:

API versioning is the practice of transparently managing changes to your API.

Versioning is effective communication around changes to your API, so consumers know what to expect from it. You are delivering data to the public in some fashion and you need to communicate when you change the way that data is delivered.

What this boils down to, in the nitty gritty, is managing data contracts and breaking changes. The former is the primary building block of your API and the latter reveals why versioning is needed.

Data Contracts

An API is an Application Programming Interface, and an interface is a shared boundary to exchange information. The data contract is the heart of this interface.

A data contract is an agreement on the shape and general content of the request and/or response data.

To illustrate a data contract, here's a basic JSON response body:

{
  "data": [
    {
      "id": 1,
      "name": "Product 1"
    },
    {
      "id": 2,
      "name": "Product 2"
    }
  ]
}

It's an object with a data property that is an array (list) of products, each with an id and name property. But the data property could have just as easily been called body, and the id property on each product could have been a GUID instead of an integer. If a single product was being returned, data could be an object instead of an array.

These seemingly subtle changes would have made for a different agreement, a different contract, regarding the "shape" of the data. The data shape could apply to property names, data types, or even the expected format (JSON vs. XML).

Why is Versioning Needed?

With APIs, something as simple as changing a property name from productId to productID can break things for consumers. This very thing happened to our team last week.

Thankfully, we had tests to catch changes to the API contract. However, we shouldn't have needed those tests, because the maintainers of the API should have known this would be a breaking change.

Breaking Changes

This was a breaking change to the agreed upon data contract because their change forced us to change our application as well.

What constitutes a "breaking change" in an API endpoint? Any change to your API contract that forces the consumer to also make a change.

Breaking changes primarily fit into the following categories:

1. Changing the request/response format (e.g. from XML to JSON)
2. Changing a property name (e.g. from name to productName) or data type on a property (e.g. from an integer to a float)
3. Adding a required field on the request (e.g. a new required header or property in a request body)
4. Removing a property on the response (e.g. removing description from a product)

API Change Management

It is never wise or kind to force consumers of an API to make a change. If you must make a breaking change, that's what versioning is for, and we'll cover the most effective ways to version your application and endpoints.

But first let's briefly discuss how to avoid breaking changes in the first place. We could call this API change management.

Effective change management in the context of an API is summarized by the following principles:

• Continue support for existing properties/endpoints
• Add new properties/endpoints rather than changing existing ones
• Thoughtfully sunset obsolete properties/endpoints

Here's an example that demonstrates all three of these principles in the context of the response for requesting user data:

{
  "data": {
    "id": 1,
    "name": "Carlos Ray Norris",     // original property
    "firstName": "Carlos",           // new property
    "lastName": "Norris",            // new property
    "alias": "Chuck",                // obsolete property
    "aliases": ["Chuck", "Walker"]   // new property
  },
  "meta": {
    "fieldNotes": [
      {
        "field": "alias",
        "note": "Sunsetting on [future date]. Please use aliases."
      }
    ]
  }
}

In this example, name was an original property. The firstName and lastName fields are being implemented to provide a more granular option, in the event that the consumer wants to display "Mr. Norris" with some string interpolation but without having to parse the name field. However, the name property will be supported in an ongoing fashion.

alias, on the other hand, is going to be deprecated in favor of the aliases array--because Chuck has so many aliases--and there is a note in the response to indicate the sunsetting time frame.

How Do You Version an API?

These principles will take a long way in navigating changes to your API without needing to roll a new version. However, sometimes it's avoidable, and if you need a brand new data contract, you'll need a new version of your endpoint. So you'll need to communicate that to the public in some way.

As an aside, do note that we're not talking about the version of the underlying code base. So if you're using semantic versioning for your application that also supports a public API, you will likely want to separate those versioning systems.

How do you create a new version of your API? What are the different methods for doing so? You'll need to determine what type of versioning strategy you want to take in general, and then as you develop and maintain your API, you'll need to determine the scope of each version change.

Scope

Let's tackle scope first. As we explored above, sometimes data contracts will be compromised by a breaking change, and that means we'll need to provide a new version of the data contract. That could mean a new version of an endpoint, or it could mean a change at a more global application scope.

We can think of levels of scope change within a tree analogy:

• Leaf - A change to an isolated endpoint with no relationship to other endpoints
• Branch - A change to a group of endpoints or a resource accessed through several endpoints
• Trunk - An application-level change, warranting a version change on most or all endpoints
• Root - A change affecting access to all API resources of all versions

As you can see, moving from leaf to root, the changes become progressively more impactful and global in scope.

The leaf scope can often be handled through effective API change management. If not, simply create a new endpoint with the new resource data contract.

A branch is a little trickier, depending on just how many endpoints are affected by the data contract change on the resource in question. If the changes are relatively confined to a clear group of related endpoints, you could potentially navigate this by introducing a new name for the resource and updating your docs accordingly.

# variants, which has a breaking change, is accessed on multiple routes
/variants
/products/:id/variants

# we introduce product-variants instead
/product-variants
/products/:id/product-variants

A trunk refers to application-level changes that are often a result of a change in one of the following categories:

• Format (e.g. from XML to JSON)
• Specification (e.g. from an in-house one to JSON API or Open API)
• Required headers (e.g. for authentication/authorization)

These will necessitate a change in your overall API version, so you should plan carefully and execute the transition well.

A root change will force you to go one step further in ensuring that all consumers of all versions of your API are aware of the change.

Types of API Versioning

As we turn to different types of API versioning, we'll want to use these insights into varying scopes of API changes to evaluate the types. Each approach has its own set of strengths and weaknesses in addressing changes based on their scope.

There are several methods for managing the version of your API. URI path versioning is the most common.

URI Path

http://www.example.com/api/v1/products
http://api.example.com/v1/products

This strategy involves putting the version number in the path of the URI, and is often done with the prefix "v". More often than not, API designers use it to refer to their application version (i.e. "trunk") rather than the endpoint version (i.e. "leaf" or "branch"), but that's not always a safe assumption.

URI path versioning implies orchestrated releases of application versions that will require one of two approaches: maintaining one version while developing a new one or forcing consumers to wait for new resources until the new version is released. It also means you'd need to carry over any non-changed endpoints from version to version. However, for APIs with relatively low volatility, it's still a decent option.

You would likely not want to relate your version number to that of the endpoint or resource, because it would easily result in something like a v4 of products but a v1 of variants, which would be rather confusing.

Query Params

http://www.example.com/api/products?version=1

This type of versioning adds a query param to the request that indicates the version. Very flexible in terms of requesting the version of the resource you'd like at the "leaf" level, but it holds no notion of the overall API's version and lends itself to the same out-of-sync issues mentioned in the above comment on endpoint-level versioning of the URI path.

Header

Accept: version=1.0

The header approach is one that provides more granularity in serving up the requested version of any given resource.

However, it's buried in the request object and isn't as transparent as the URI path option. It's also still hard to tell whether 1.0 refers to the version of the endpoint or the API itself.

Integrating Types

Each of these approaches seem to have the weakness of either favoring a "leaf" or "trunk" scope, but not supporting both.

If you need to maintain the overall API version and also provide support for multiple versions of resources, consider a blend of the URI Path and Query Params types, or a more advanced Header approach.

# URI path and query params combo
http://api.example.com/v1/products?version=1
http://api.example.com/v1/products?version=2

# Extended headers, for http://api.example.com/products
Accept: api-version=1; resource-version=1
Accept: api-version=1; resource-version=2

Conclusion

We've covered a lot of ground here, so let's recap:

• API versioning is the practice of transparently managing changes to your API.
• Managing an API boils down to defining and evolving data contracts and dealing with breaking changes.
• The most effective way to evolve your API without breaking changes is to follow effective API change management principles.
• For most APIs, versioning in the URI path is the most straightforward solution.
• For more complex or volatile APIs, you can manage varying scopes of changes by employing an integration of URI path and query params approaches.

Although these principles should provide clear direction in how to effectively manage change to your APIs, evolving an API is potentially more of an art than a science. It requires thought and foresight to create and maintain a reliable API.