ASP.NET Web API 2: designing URI contracts with attribute routing
Attribute routing in ASP.NET Web API 2 allowed URI patterns to be associated directly with controllers and actions. This was useful for resource hierarchies that could be awkward to express through a shared convention-only routing table.
Archive retrospective · Topic year 2013
Historical change and problem
Attribute routing in ASP.NET Web API 2 allowed URI patterns to be associated directly with controllers and actions. This was useful for resource hierarchies that could be awkward to express through a shared convention-only routing table. A readable address, however, is not proof that the responding application will return the correct record to an authorized user. Readable API paths matter especially for long-lived client applications. Changing a URL today does not update every installed mobile app immediately. A route redesign should therefore begin with an inventory of existing calls and supported client versions. Compatibility is an external contract, not just a controller refactoring detail.
A concrete design scenario
A customer-to-orders path can make a parent-child relationship visible in the URI. The route attribute determines which action receives the request; ownership checks, query filters, and permissions belong in separate controls. A syntactically valid identifier in the path does not give its caller the right to inspect another customer's data. When a path contains both a customer identifier and an order identifier, the server should verify that the order actually belongs to that customer. The mere existence of the order record may be insufficient. That relationship check helps prevent incorrect resource selection and unauthorized exposure.
Boundaries and failure modes
Route constraints, optional segments, and version prefixes shape the contract. Similar patterns can collide or route a request to an unexpected action. Changing existing URIs also creates a compatibility cost for installed clients. Documentation needs to explain not just the path but the HTTP method, response shape, and failure codes that callers may depend on. A route constraint can reject malformed identifiers early, but format validation is not authorization. A caller who knows a correctly shaped numerical ID may still lack permission to access it. Routing and business access rules operate at different layers and should have different tests.
A reproducible acceptance experiment
Test valid and invalid identifiers, overlapping route patterns, and method differences. Confirm that an unauthorized identity cannot gain access merely by constructing a valid URI. Exercise older client URLs before deciding that a routing migration is safe. An HTTP 200 status alone does not prove the endpoint returned the intended resource. Before migration, test root resources, nested resources, and unknown paths. Error responses should use status codes such as 400, 403, and 404 consistently without exposing unnecessary internal details. Testing only successful calls misses a substantial part of the contract that clients depend on.
Maintenance and the lasting lesson
The enduring lesson is that URI design is a long-lived client contract rather than an internal implementation detail. Modern ASP.NET Core routing is not identical to historical Web API 2. Nevertheless, meaningful resource paths, object-level authorization, and compatibility remain distinct requirements in current API design. Good API design is more than selecting a routing feature. Paths, HTTP methods, authentication, record ownership, and error responses form one coherent public contract. Attribute routing made one part easier to express explicitly, while the remaining responsibilities still belong to application design and testing.
Comments
No comments yet. Be the first to contribute.
Write a comment
Sample comments and editor reply
Discussion example — not real reader feedback. Names and conversations in this area are fictional. Likes and replies here are not saved and do not count as real engagement.
Example counters: 20,056 reads · 276 likes — not actual analytics
Does restricting a route parameter to integers also authorize access?
A route constraint helps select an action; it does not determine permission to read or change a record. Test route misses, validation failures, and unauthorized access separately.
We should also discuss maintenance cost. An easy rollout does not guarantee trouble-free upgrades.
I would start with a pilot and measurable success criteria rather than assuming a launch means proven value.
Reading “ASP.NET Web API 2: designing URI contracts with attribute routing” today, which limitations of that period still matter?
The topic year provides the historical context. Applying an archive finding today requires checking the source date and current conditions.
Which source would you recommend as a starting point for someone new to yazilim?
Which variables should stay fixed when comparing this result in another setting? A single measurement may not tell the whole story.
Could this link to another archive article on the same subject? Comparing the developments over time would be helpful.
The sources and archive links offer a starting point for further reading. Compare methods and scope as well as the headline claims.
Which questions remain open in “ASP.NET Web API 2: designing URI contracts with attribute routing”? It would help to separate established findings from expectations.