When ASP.Net Web API first came out, it was a revelation. Things that went through my mind back when it was first released: "I don't have to use WCF anymore?" "No more mile-long web.config?" "I can wash my hands of SOAP?" Yeah, that last one's pretty clever, I know. Anyway, this framework, it seemed promising early on, but I've become disappointed in ASP.Net Web API as time goes on because it hasn't evolved much
For the most part, the only thing this "framework" provides is routing and the fact that it will spit out JSON responses to requests. Other than that, Web API doesn't give you much and it's been that way for a long time. But, what more could you ask for? I'll tell you.
My Dream ASP.Net Web API Framework Would:
- Not require controllers at all (blasphemy!).
- Provide built-in paging, sorting and querying.
- Output standardized JSON (JSON API).
- Provide built-in HATEOAS support.
- Allow differentiating standard REST calls vs. RPC calls.
Is that too much to ask? Apparently it is. I haven't found a framework out there that does these things and I've been looking for a long time. Maybe (hopefully) I'm wrong and such a framework does exist and you, dear reader, know about it. If so, comment below.
Anyway, let me elaborate a bit on these points.
What I mean here is, I don't want to write a unique controller for every entity. Talk about violating the DRY principle. Most entities do the same thing: they provide methods to GET, POST, PUT, PATCH and DELETE. This is predictable behavior. Ideally, you could define an entity and it would poses a route using the entity name by convention and it could be mapped to methods in the data or business layer. This could become restrictive, yes, but that's why there would also be a need to have a mechanism to handle RPC calls, things that fall outside of the above pattern.
Built-in Paging, Sorting and Querying
This is pretty self-explanatory. Any route for a resource would predictably provide paging (in the query string or perhaps via headers), sorting and querying. Querying in some instances would work like a WHERE clause or it could also allow the consumer of the API to restrict a response to only a few properties in the response type.
Standardized JSON and HATEOAS
It would be nice to have something more than raw JSON as the format for responses so that API consumers could count on a predictable format. Also, providing resource links would help discoverability a great deal. Standardizing does present the risk of becoming a monolith (SOAP anyone?) but having no standard tends to result in requiring more documentation and tribal knowledge.
REST and RPC
Let's face it, most Web APIs need to do more than just act RESTful. We invariably need to provide some type of remote procedure call as well. For instance, we might need an end-point that processes an e-commerce transaction. Where does that fit into the standard interaction of a single resource? Or, we might need an end-point to present a report that can't really be represented with a single entity. This is where controllers would have to exist, for the RPC calls that don't fit the predictable model of RESTful resources.
To my knowledge, such a Web API framework doesn't exist in the .Net ecosystem, well, at least not in the wild. What we have is a very basic means of handling routes to controllers and outputting JSON responses. That was a good start, but it's time for the ASP.Net Web API framework to evolve.