Restful WebAPI VS Regular Controllers

Question

I'm doing some R&D on what seems like a very confusing topic, I've also read quite a few of the other SO questions, but I feel my question might be unique enough to warrant me asking. We've never developed an app using pure WebAPI.

We're trying to write a SPA style app, where the back end is fully decoupled from the front end code

Assuming our service does not know anything about who is accessing/consuming it:

WebAPI seems like the logical route to serve data, as opposed to using the standard MVC controllers, and serving our data via an action result and converting it to JSON. This to me at least seems like an MC design... which seems odd, and not what MVC was meant for. (look mom... no view)

What would be considered normal convention in terms of performing action(y) calls?

My sense is that my understanding of WebAPI is incorrect.

The way I perceive WebAPI, is that its meant to be used in a CRUD sense, but what if I want to do something like: "InitialiseMonthEndPayment".... Would I need to create a WebAPI controller, called InitialiseMonthEndPaymentController, and then perform a POST... Seems a bit weird, as opposed to a MVC controller where i can just add a new action on the MonthEnd controller called InitialisePayment.

Or does this require a mindset shift in terms of design?

Any further links on this topic will be really useful, as my fear is we implement something that might be weird an could turn into a coding/maintenance concern later on?

Answer 1

The way I perceive WebAPI, is that its meant to be used in a CRUD sense

wrong.

I don't know about that "WebAPI" style, but any web service is way more than CRUD.

Most of the 'classic' services (SOAP, XMLRPC, etc) are an implementation of the RPC (remote procedure call) style, in effect, you make function calls from the client to a server. What each call does is up to you, but it's better if you make sure that each call leaves the system in a complete, consistent state. It's better to include more data in a single call and not to require two calls to make what is conceptually a single operation.

A different proposal is REST style, which puts emphasis in the things that are handled and not on the procedures. That's why so many simplistic libraries just make a remote-accessible CRUD and call it a day.

But a real RESTfull API is not CRUD, because a "resource" is not a database record. Resources are the conceptual entities of your system, the "representations" (typically JSON data) embody the state of those entities. The PUT, POST and DELETE verbs modify that state, maybe via some sub-resources. (adding a comment to a forum thread, deleting a user from the list of who can access something, etc). The HATEOAS principle lets you 'browse' the state of the system, and the relationships and lists give you more URL endpoints to handle all that.

In your example, adding an 'month end payment' to a list of payments (or maybe the list of payments of a specific payee?) is simply a POST with the payment data to the URL that represents the payment 'container'. The server should do all the needed creation, initialization and relationships to make sure that in the end the system is in a new complete state, no 'in betweens'.