Service Generation Outcome

This article is relevant to entity models that utilize the deprecated Visual Studio integration of Telerik Data Access. The current documentation of the Data Access framework is available here.

The Service Wizard allows you to generate ASP.NET Web API Services based on Telerik Data Access. This topic discusses the changes that the wizard will make to your project.

References

The wizard adds references to:

Telerik.OpenAccess.dll
Telerik.OpenAccess.35.Extensions.dll
Newtonsoft.Json.dll
System.Net.Http.dll
System.Net.Http.Formatting.dll
System.Net.Http.WebRequest.dll
System.Web.Http.dll
System.Web.Http.WebHost.dll
<Your Telerik Data Access Model Project>

Generated Files

When ASP.NET Web API Service is generated, the wizard will automatically create several additional files and will add them to the output project.

OpenAccessBaseRepository.cs and <XXX>Repository.cs - contains implementation of the Repository pattern that enables access to the data shaped by your decision in step 3 of the wizard. Provides CRUD operations interface to the database. The Repository pattern allows you to separate the data access from the service implementation. That way, you can change the backing store without rewriting the service classes (controllers).
OpenAccessBaseApiController.cs - generic base controller that handles CRUD operations over your domain model.
<XXX>Controller.cs - contains specific controllers for the domain classes exposed by your decision in step 3 of the wizard.
Global.asax.Routes.cs - contains a default route for the generated ASP.NET Web API Service.

Each controller generated by the Service Wizard exposes several methods for CRUD operations. CRUD stands for "Create, Read, Update, and Delete" which are the four basic database operations. For example, consider the CategoriesController:

Action	HTTP Method	Relative URL	Controller Method
Get a list of all categories.	GET	/api/categories	Get() - This is a generic method defined in the base OpenAccessBaseApiController.
Get category by Id.	GET	/api/categories/Id	Get(Int32 id)
Create a new category.	POST	/api/categories	Post(TEntity entity) - This method is defined in the base OpenAccessBaseApiController.
Update an existing category.	PUT	/api/categories/Id	Put(Int32 id, Category entity)
Delete an existing category.	DELETE	/api/categories/Id	Delete(Int32 id)

Note that some of the URIs include ID parameters in their path. To retrieve a list of all categories, the client should sent a GET request to http://hostname/api/categories. To retrieve an individual category, e.g. to get the category whose ID is 1, the client should send a GET request to: http://hostname/api/categories/1.

The four main HTTP methods are GET, POST, PUT and DELETE. They can be mapped to CRUD operations as follows:

GET retrieves the resource at the specified URI.
PUT updates a resource at a specified URI. Sometimes PUT can be used to create a new resource at a specified URI. But in this tutorial, it is used only for update.
POST creates a new resource.
DELETE deletes a resource at a specified URI.

Global.asax.Routes.cs

In ASP.NET Web API, the public methods of the controllers are called action methods. When the Web API framework receives a request, it routes the request to an action. To determine which action to invoke, the framework uses a routing table. The Service Wizard creates a default route.

RouteTable.Routes.MapHttpRoute(name: "DefaultApi",
                               routeTemplate: "api/{controller}/{id}",
                               defaults: new
                               {
                                   id = RouteParameter.Optional
                               });

RouteTable.Routes.MapHttpRoute(name:="DefaultApi",
          routeTemplate:="api/{controller}/{id}",
          defaults:=New With { .id = RouteParameter.[Optional] })

The default route template for ASP.NET Web API is "api/<controller>/<id>. Where <controller> and <id> are placeholder variables. When the Web API framework receives a request, it tries to match the URI using the route templates. If no route template is found, i.e. there is no match, the client recieves 404 Not Found. For example, the following URIs match the default route templates: '/api/categories' and '/api/categories/1'. However a request to the following URI will return 404 Not Found - '/categories/1'. The URI lacks the 'api' segment.

Once a matching route template is found, the Web API framework selects the controller and the action by using the following algorithm:

To find a controller, Web API adds "Controller" to the value of the <controller> variable. For example, in the following URI - '/api/categories', Web API will look for a controller named CategoriesController.
To find the action, Web API looks at the HTTP method. Then looks for an action whose name begins with that HTTP method name. For example, with a GET request, Web API looks for an action that starts with "Get...", such as Get() or Get(Int32 Id).
Other variables, such as <id> are mapped action parameters.