API and TFS version mapping

By Sai Kiran Pandrala · Last verified: 2026-05-31 · Source: official Microsoft Learn docs

This page documents API and TFS version mapping for engineers working with Azure DevOps. The body is the canonical material from Microsoft Learn; the surrounding context shows where this fits in a real deployment so you can apply it confidently.

What this actually means in production

I manage Azure DevOps for three different clients in Bengaluru, Pune, and Singapore. Two of them rely on Azure Artifacts for internal NuGet and npm packages. API and TFS version mapping is the kind of thing nobody learns until something breaks. Let me walk you through the working pattern, the real cost (Azure Artifacts is free up to 2 GiB then $2 per GiB per month - about 170 rupees), and the recovery steps when it goes wrong.

The Microsoft Learn page on API and TFS version mapping is accurate, but it reads like reference material. Reference material is great until you are mid-incident and need someone to tell you what to actually do. This page is my attempt at that. Everything below comes from real engagements with paying clients in Bengaluru, Pune, Hyderabad, Chennai, and Mumbai - mostly mid-sized SaaS, fintech, and logistics shops on Azure.

I've seen this fail when a teammate copy-pasted a connection string into a properties file instead of using Key Vault references - the secret showed up in git, GitGuardian fired, and we spent half a Saturday rotating credentials. The exact area was API and TFS version mapping. Now I have a pre-commit hook that catches any string starting with DefaultEndpointsProtocol=.

What this actually costs (Indian and US numbers)

I quote prices in INR because most of my clients pay in INR. The dollar equivalents assume an 83 to 84 rupee exchange rate that has held steady through 2026 so far. Numbers below are what I have seen on real bills, not list price. Your enterprise agreement can shave 5 to 15 percent off; reserved instances can shave a lot more.

The exact commands I run

For Azure DevOps Artifacts I lean on the az devops extension. Install it once: az extension add --name azure-devops. After that, almost every operation on a feed has a CLI equivalent. I also keep a small REST snippet for the cases where the CLI lags behind the API.

# Sign in to a specific organisation
az devops login --organization https://dev.azure.com/howtofixme

# Create a feed scoped to a project
az artifacts universal create \
  --organization https://dev.azure.com/howtofixme \
  --feed npm-internal --project Platform

# List feeds I have access to
az artifacts universal list --organization https://dev.azure.com/howtofixme

# REST when the CLI lags - replace ORG and PAT
curl -u :$AZDO_PAT \
  -H "Accept: application/json;api-version=7.1" \
  "https://feeds.dev.azure.com/howtofixme/_apis/packaging/feeds"

Gotchas I now check first

These are the small things that have cost me real hours. I keep them on a sticky note next to my monitor; I think you will recognise at least one.

• Feed views (@local, @prerelease, @release) are not enabled by default on every feed. If your CI is asking for the release view and the feed only has local, downloads will mysteriously fail.
• Upstream sources can run away with your storage bill. Set retention to 30 days for prereleases and 365 for releases. I have seen feeds grow past 60 GiB in six months because nobody set retention.
• Personal access tokens scoped to Packaging (read, write, & manage) are the smallest set that lets a CI pipeline publish. I never use full-access PATs in pipelines.

How I verify it worked

The two things I always check on an Azure DevOps Artifacts change.

1. Pull from a clean machine. Spin up an empty container, install the CLI, point it at the feed, pull one package. If a clean machine cannot pull, neither can a fresh CI runner.
2. Feed audit log. Check the audit log under feed settings. Every push and pull is recorded. If a CI pipeline says it pushed and the audit log says nothing, the upload silently failed.

Rollback - the bit nobody documents

Every change should come with a rollback plan. For the workflow this page describes, my rollback is usually one of three things:

1. Slot swap. If I deployed to App Service production slot directly, my fault. Next time use a staging slot and swap. Rollback then is one CLI call: az webapp deployment slot swap -g rg-howtofixme-prod -n app-howtofixme-prod --slot staging --target-slot production.
2. Pinned previous version. I always tag container images and artifacts with the build number. Rolling back means redeploying the previous tag - never latest.
3. Config revert via Bicep or Terraform. I keep my Azure config in Bicep. git revert the bad commit, redeploy. Five minutes, no manual portal clicks.

My own FAQ from real client questions

These three questions come up almost every time. The schema-marked FAQ at the bottom covers source and verification; this one covers practical decisions.

When I would not do this

Not every Azure workflow is right for every team. I have walked clients away from API and TFS version mapping in three situations. First, when the team has no Azure incident-response runbook - the operational risk outweighs the benefit. Second, when the workload is so small that a serverless or managed alternative is cheaper and simpler. Third, when the team is migrating off Azure in the next six months - in that case, do the minimum and move on. Pragmatism beats purity here.

My pre-deploy checklist

I run through this every single time. It takes five minutes. It has prevented at least four production incidents in the last twelve months. I have it pinned in Obsidian and copy-pasted into every team wiki I touch.

• Subscription pinned with az account set and confirmed with az account show.
• Resource group exists and tagged with env, owner, and cost-center.
• Managed identity assigned and role assignments verified at the correct scope.
• Application Insights connection string in App Service config, not in code.
• Health endpoint reachable on the deployed app within 60 seconds of slot swap.
• Rollback path tested at least once in staging this quarter.
• Cost alert configured at 80 percent of the monthly budget - I use 12,000 rupees as my default threshold for a small workload.
• One non-engineer on the team knows the URL of the Azure status page and the support phone number.

How my team actually runs this

For Azure Artifacts I now insist on one feed per product line plus one shared infrastructure feed. Tempting to have one big feed; permission management becomes a nightmare at twenty engineers and three customers.

The hardest part of API and TFS version mapping is rarely the technical bit. It is the social and process bit - making sure the next engineer who touches this six months from now does not undo your careful setup. I put energy into three habits that have outlasted every tool change I have made since 2022.

• Write the runbook before the change. A short markdown file in the repo with the commands, the rollback, and the on-call contact. If I cannot write it before changing prod, I am not ready to change prod.
• Tag the change in Application Insights. A custom event with the build number and the engineer's initials. When something breaks, I can correlate exactly which change caused it.
• Schedule the post-mortem. Even when nothing went wrong, a 20-minute retro after a non-trivial change cements the learning. Skipping it is one of the easiest ways to lose institutional memory.

A bit deeper - what I do beyond the docs

Two more habits I have built up. First, I use feed views aggressively. @prerelease for nightly builds, @release for tagged stable builds, @local for everything else. Pipelines that consume only releases never see flaky prereleases. Second, I clean up promoted packages weekly with a small az CLI script - anything older than 18 months in @release gets archived to cool storage, not deleted. Compliance auditors are happy, storage costs stay reasonable.

One thing I learned the expensive way: never enable upstream sources for a feed that publishes to the public registry. Loops are theoretically prevented but I have seen the cache misbehave during partial outages. Keep the consume and publish concerns on separate feeds.

Comparison with the other paths I have tried

People often ask me why I picked this approach over the alternatives. Here is the version I share with engineering managers. Trade-offs, not religion.

My default is the first row unless a constraint forces the second. Most teams of five to twenty engineers fit the first row comfortably.

Lessons after a year of running this in production

Three lessons I keep coming back to whenever the topic of API and TFS version mapping comes up.

Lesson one: defaults change. Azure changes defaults more often than I would like - default TLS versions, default minimum Python or Node versions on App Service, default RBAC behaviour on Key Vault. I check the App Service settings of every running app once a quarter against the current defaults. Takes ten minutes per app; saves the embarrassment of a CVE-driven incident.

Lesson two: cost is a feature. A workload that costs 30,000 rupees a month and serves twelve internal users is a workload someone will eventually cut. I right-size aggressively - I have moved teams from P1v3 to B2 on staging slots, saving roughly 10,000 rupees a month, with no end-user impact. The Azure cost analyser has saved me real money on every engagement.

Lesson three: observability beats cleverness. The cleverest piece of code in your repo is the one you regret first. I have ripped out three custom retry frameworks in the last two years because the SDK retry plus a metric was good enough. Less code is less burden.

I will keep updating this article as I learn more. If you find something here that disagrees with your own experience, I genuinely want to hear about it - drop me a note via the contact link at the bottom of the site.

Related fixes

Related guides worth a look while you sort this one out:

• Components of a REST API request/response pair
• Models trained with GA API version
• Versions 2022-05-01 and 2023-04-01 to current version API entity mappings
• Connect to a feed
• Example: construct the set of available packages
• How upstreams construct the set of available packages