I am wondering if there is any written standard on the naming of controllers in asp.net core/mvc/api?
I am not really finding anything.
Thanks
The standard is implied with REST Api Design standard.
That means if you are providing a REST point for the handling of multiple countries you would create a CountriesController which would be routed to by asp from https://localhost:443/countries/.
The convention is name it according to the route it should have, which in case of an API should be countries to conform to REST principles. However, that convention is based on utilizing a default route which simply maps whatever comes before Controller as part of the path. With attribute routing, or even simply just custom standard routing, you can make the route whatever you want, which then means that the controller could be named whatever you want, as it's no longer being utilized directly as part of the route.
Long and short, CountriesController is probably better, since it aligns better to the route it should have, but ultimately, there's no hard and fast rule here. As with most questions like this, the only answer is the one that makes the most sense for you, your team, and your application, which none of us here can dictate for you.
Related
/controller/action/id
or
/controller/id/action
Which is more common? Which is preferable and why?
Are there any pro's / con's of using one or the other?
Edit:
Or, perhaps to think of this question in a different way, why do most MVC frameworks (ASP.Net MVC, Grails, Spring MVC) default to the /controller/action/id URL pattern? Is there some advantage to this?
Neither of these are RESTful. There should not be verbs/actions in a URL. Those are confined to the HTTP method for good reason (so that clients can interact with your service without knowing anything specific about it).
If you can not do anything except GET and POST, use POST to send an action parameter to /controller/id
Asp.Net MVC uses /controller/action/id. So that is what you'll most often see in that environment. I do not see any technical benefits but simply going with a common pattern can make things easier to understand.
I definitely prefer /controller/action/id. This feels to me more like it is identifying a resource (a noun) rather than identifying an action on that noun (a verb).
In addition to the exact URL to the resource, you need to consider how you are mapping the HTTP verbs. In my experience, we have shuffled the URL around based on what made most sense when combined with the verbs. That said, we also have a couple places we broke the canonical approach for convenience sake (for example, exposing a certain delete action with a GET so that users could perform the action via a browser).
Also take a look at this discussion for more.
REST URL structure advice
What are extensibility points of URL generation in ASP.NET MVC?
Routes - virtual path depends on it
???
Addendum 1
Particularily, I need to control not only path part of URL but the host also. And I'd like to embed my generation logics into MVC Framework so that any call to standard Html.ActionLink method would involve my logics. It would be perfect. However, investigating MVC sources I'm desperate to achieve my goal with an easy way.
Routes is pretty much where it's at. Remember, though, that you can subclass Route and provide your own implementation that does not use key/value URI templates.
There's nothing stopping you from writing your own solution from the ground up, but there's not much point since there's already an extensible foundation for you to work with.
Routing extensibility points
Routes
Route constraints
Route handlers
In your particular case, you will have to write your own route that will populate additional RouteData items related to host. Parsing your URL will be totally on you.
"{host}/{controller}/{action}"
Maybe also create your custom route handler that will make host parameter mandatory. But that already depends on your particular needs.
Edit
I guess that this article about domain routing may be of some help to you. It looks preety straight forward and uncompicated.
Indeed, it's impossible to reach desired flexibility since Route gives just VirtualPath portion during URL generation.
I always try to make my applications as RESTful as possible but I've recently begun working on a complex project that requires multiple additional methods in my controller.
I normally achieve this by adding another :collection to the route but it seems like a workaround and in on scenario I have 5.
Are there any best practices for handling the extra methods in a controller? They are generally simple forms that updates a model.
The other solution, which is what I do, is every time you find yourself creating an action that doesn't fit into the RESTful actions, eg Search, so you might find yourself making a search action on an Article controller, what you could do instead of creating this action is create a Search controller instead, and use RESTful actions inside of that instead. There is no rule saying you need to use all the actions, you might only need one or two, but it keeps your API RESTful and your code organised.
This is not a hard and fast rule, but I have certainly found it helpful when I try to decide where to put stuff.
I think there's a bit of confusion in the Rails community about how and where to use the word "RESTful". Strictly speaking, the only thing that can be RESTful is your web API (as railsninja already mentioned). That the code of an application that conforms to the REST conventions (the application with REST API) can usually be organized into a set of controllers (that match the resources) and methods in these controllers (that match the four verbs of the HTTP protocol) is nothing but a hint of how to keep your application clean and organized.
If we want to talk about a RESTful Rails application, we can't just talk about RESTful controllers - there's nothing RESTful about just controllers themselves. It's possible to have a complex web application with only one controller (and myriad of methods) that represents many resources and is perfectly RESTful.
That said, it's pretty OK to add more methods to your controller. Sometimes, it's good to extract some of these extra methods and create a completely new controller - make this any time you feel good about it (rule of a thumb: create new controller anytime you are able to identify it with some self-sufficient resource, ie. a resource which could exist just by itself). Sometimes though, it'd be silly to extract some resource to a different controller. Say you have a resource which has a status attribute. It makes sense to perceive this status attribute as a resource by itself and perform at least one action on it (update), but it won't make any good to extract it to a different controller.
There is a Railscast about this topic, adding custom actions to an otherwise RESTful controller.
Edit: I see that you've mentioned the method in the Railscast as a workaround already. :-) I believe the only other "pure" way to handle it would be to add additional controllers as required to support the actions you want.
"I normally achieve this by adding another :collection to the route but it seems like a workaround and in on scenario I have 5. "
This sounds perfectly fine to me. REST is not about the crud operations and your concern seems to stem from the fact that you are doing more than the basic crud operations but there's nothing wrong with that.
I've been toying with the SimplyRestfulRouting assembly that comes with the MvcContrib extras, and for the most part I really like that it quickly sets up my routes and leaves me with a good convention to follow in my controllers. However, I'm still trying to wrap my head around REST as it applies to rich internet applications and occasionally feel pigeon holed when I need to do something that falls outside the scope of those 8 or 9 default routes. [Edit: By "pigeon holed", I simply mean I feel like I'm dirtying up the application when I have to create a controller action that is outside the definition of the default "restful routes".]
I heard a comment from a REST proponent in which he stated his opinion that the MVC framework is inherently RESTful, and it got me thinking a bit more about what libraries like the MvcContrib SimplyRestfulRouting are actually buying me.
Not having read a lot about the concrete pricinples of REST, I'm looking for input as to what benefits might come from enforcing such a thing in the context of a forms-over-data, RIA. And with regards to AJAX, how does a RESTful architecture affect my client interaction?
It's likely I'm misunderstanding the use of REST in this context, and would appreciate some StackOverflow mojo to get my head on straight.
The main benefit I can see in enforcing RESTful routes -- regardless of the framework used -- is consistency. You'll always be able to know how the API will work for any resource, which will in effect give you a self-documenting API.
It also provides a wonderful constraint while architecting the application. Rather than having an API with a blank slate that could get complicated very quickly, constraining the routes to the basics will give you guidance as to which resources you'll need to create.
For more of the basic principles surrounding REST, I'd recommend reading this thread.
Being RESTful is more than just having clean URLs.
At an architectural level, REST is about organizing your application functionality in terms of resources, and exposing a fixed and uniform set of CRUD operations on them (e.g. HTTP POST/GET/PUT/DELETE methods). This is known as Resource Oriented Architecture.
In contrast, with Service Oriented Architecture you typically organize application functionality in terms of processes or components, and expose non-uniform, application specific methods on them (e.g. via SOAP).
Note, you can have clean URLs but still end up following non-RESTful SOA design principles.
UPDATE: Sorry, didn't really answer the question, got hung up on use of "RESTful" terminology. If you're just talking about the benefits of clean URLs (REST/SOA argument aside), the typical argument is better SEO optimization and user-friendliness (user can better make sense of and modify URLs).
the advantage is that if you have some adress and from that adress you getting something, then you can call that adress from anywhere you want in you code, and you will get exactly same thing :)
and in concrete example, if you have route that can return some html full with data(user control for example), then you can call it from ajax, from your desktop application or even from your web service...it is very powerfull because you WILL have some functionality repeated over your application...and because some html that you getting from that restful service giving you exactly one view with exactly one functionality, you can call it dynamically from dialog or from page or from your desktop application or from anywhere...
and when you add to this that you can call this adress with parameters, exactly like some method, you can now see how powerfull this can be in creating dynamic pages and web sites/systems
hope this helps
So I am in a situation where I have to decide whether or not to have a separate controller for a particular piece of code. We have a home page that acts like a hub for the rest of the site. The page is accessible to all users (logged in as well as non-logged-in). I was thinking about having home as a separate controller and an action called index. Thinking about this situation, I started wondering if there are any rules or guidelines on this front.
My perception has been that if a code revolves around an entity, separation is needed. (Similar to REST guidelines) If the entity is a noun, it should be a controller. If the entity is a verb, it should probably be an action and should reside in the controller whose name is the same as that of the noun that the verb refers to. Some colleagues suggested that since this is one action, it should reside in the some existing controller and should be named home. I strongly disagreed, however, I could not find a trusted source that would back me up on this.
Would like to know your thoughts.
In this case I have to agree with your co-workers.
REST is a nice approach to take when dealing with resources, as you say. This allows you to create a consistent interface especially with a view to creating a web service.
However REST doesn't actually map too well to a web browser setting. You'll notice for example that even for resources your /edit and /new actions are just GET requests returning an HTML form pointing to the relevant RESTful action. 'edit' and 'new' aren't RESTy at all.
Similarly, the home page is generally a user-friendly amalgamation of various data, not suited to a RESTful interface. So either just stick an extra controller in with one action, or alternatively use an existing controller's 'list' action as the home page
The problem starts with the phrase
If an entity is a verb
If you are attempting to produce a RESTful architecture, an entity cannot be a verb. The only verbs allowed if you are using HTTP are GET, PUT, POST, DELETE, HEAD, OPTIONS. All entities should be mapped to some noun and if you are trying to retrieve that entity you should be using the verb GET. Personally, I would map that to the method Get() on my controller but I don't know if Rails lets you do that.
The quick (and unhelpful) answer is that either way works fine.
I think that everybody comes across this decision at one point, and the decision you make depends on the likely future of the website... which means it's prone to premature optimisation... but that's always the catch,
As you've probably guessed by now, "home" is in some ways a verb as well as a noun, thus why you're having trouble figuring out what to do.
The answer depends on a combination of interpretation of your website structure and how much time is available to you...
if you have very little time to work on this... then stuffing the 'home' action into another controller is often considered the expedient option. It works, it lets you move onto other (probably more productive) tasks.
However, I agree that sometimes it is good to step back and think about what you're doing and whether it could be done "better"...
in this case, though it's harder to define "better" - as it's unlikely that putting the home action in a new controller would be measurably faster... and if it's the only action int he controller... it's debatable whether it's better, architecturally, to just adding it onto an existing controller...
So we start in on what is mostly a philosophical debate... in other words, no answer will be "more correct" than the other- it's more a matter of taste and circumstance. In this case, the debate hinges on making the structure more RESTful.
To be faithful to RESTful architecture, you would indeed move the action into it's own controller... but you'd first have to identify what the entity is. The "home" page is often not readily identifiable as a specific db entity... it's more often a portal-page.
Sometimes you can pick an entity eg online shops will often have a home page that is actually a "products#index" variation, or sometimes the "home" page is a UserAccount#show page... but more often, your home page will not be simple, and will combine information from multiple entities... thus why it is difficult to decide what the "right" architecture will be.
If you cannot identify a specific entity, then there is a valid debate as to whether to move the action into a specific controller.
however, you can always create a new "entity" that is centred around the architecture of the site. This is especially likely if you are going to come up with other non-entity-specific pages for the site (eg T&Cs or an "about our company" page).
The usual fallback being a "PageController" (or similar name) which isn't linked to an Active Record model, but to a more nebulous entity, in this case a "page" which is recognisable to a user of the website (eg the "home page" and the "T&C page" and the "about page"). Each action would be for a specific page...
So, it's up to you as to whether this fits better with your view of the architecture of your system... and whether it's worth the effort... but that's my view on the debate. :)