difference between Umbraco Surface controller and API controller

Question

What is the difference between Surface and API controller for Umbraco?

In standard MVC the general rule is:

• API is used for returning data, that can be consumed by multiple applications.
• Controller is used for returning views

But I am bit unsure with Umbraco.

So far I have been using surface controller to post data from and into forms, which makes me wonder if I am using it correctly and if should I use instead API controller for this

What are your reasons for your opinion?

Answer 1

I don't think that you are mistaken. Umbraco Surface Controllers deal with front-end user interactions like posting data into forms (from http://our.umbraco.org/documentation/Reference/Mvc/surface-controllers)

A SurfaceController is an MVC controller that interacts with the front-end rendering of an UmbracoPage. They can be used for rendering Child Action content, for handling form data submissions and for rendering Child Action macros. SurfaceControllers are auto-routed meaning that you don't have to add/create your own routes for these controllers to work.

Whereas you'd use API controllers to access data in other domains, or the back-end of your current site.

There is a possibility that Umbraco will start to be more commonly used purely through its own API (using ContentService for example) and that the /umbraco/ access to the back office will become unused in more sophisticated implementations at which stage web apis will be used by controllers to connect models & views. Disconnecting umbraco from its website is a more grown-up model for a CMS and could cure many deployment issues so that nagging feeling that you should be using web api in more use cases could very well be a good one.

Answer 2

I generally use the SurfaceControllers for everything MVC. My API controllers are used for applications outside of the website to use. An example of the api controller would be one that gets all the FAQs for the website by calling /Umbraco/Api/ResourcesApi/GetFaqs as a JSONResult.

public sealed class ResourcesApiController : UmbracoApiController