Refer to Choosing WCF or Web API for additional information on WCF and Web API.
This presentation project uses Web API to provide a RESTful web service.
Notes:
If you are creating a new RESTful web service, it is recommended that you use this project type rather than the WCF RESTful Service Application.
Refer to Reference Information for Scaffolded Projects for more information.
This topic describes a simple case of adding a Web API project to an existing solution that already contains a data source project. Other use cases are also possible, such as cases where multiple data source projects exist. Refer to Reference Information for Scaffolded Projects for more information.
Routing for Web API Services
A WebAPI service can use convention-based routing, attribute routing, or a combination of both. By default, convention-based routing is used.
The HTTP verb used to access a web method is set by applying the AcceptVerbs attribute on the web method. By default, the POST verb is used.
Convention-Based Routing
Convention-based routing uses the Route Template, specified in the WebApiConfig file, to construct the Uniform Resource Identifier (URI). The default Route Template is {controller}/{action}, where “controller” is the base name of the WebApi Controller, and “action” is the name of the web method. For ePortal generated services, the web method name is the name of the client message being scaffolded. The action name can be overridden by setting the ActionName attribute on the web method.
Attribute Routing
Attribute routing is applied to individual web methods by specifying the Route attribute. The Route attribute allows specifying the URI path, optionally incorporating variable parameters in the URI.
The RoutePrefix class attribute specifies the prefix to apply to all routes using attribute routing. If the RoutPrefix is not specified, no prefix is used.
The full route is {RoutePrefix}/{Route}.
Creating a Web API RESTful Web Service Project
ePortal Developer provides two scaffolding templates for creating a WebAPI RESTful Web Service:
Unisys Web API Controller for ePortal Data Source
This template provides compatibility with previous versions of ePortal. It uses convention-based routing and the default HTTP verbs for the generated web methods.
Unisys Data Source Web API Controller Version 2
This is a new template that provides more control over naming composition of the URL (using attribute routing along with convention-based routing), specifying HTTP verb to be used, providing global option to specify route prefix and allowing parameter substitution from URI. It also provides OpenAPI (Swagger) definition for generated services with improved error handling.
Notes:
OpenAPI documentation is required for consumers of the ePortal REST Web Service. Microsoft recommends using the Swashbuckle NuGet package.
The Swashbuckle NuGet packages are included in the Unisys.mvc5.webapi.extensions NuGet package.
You can use the following URI to access the OpenAPI documentation and Swagger test page respectively:
http://<host>:<port>/swagger/docs/v1
http://<host>:<port>/swagger
If your existing projects contain a ValuesController, you should delete it so that the swagger integration functions properly.
Nuget Packages Swashbuckle and Swashbuclle.Core included in Unisys MVC 5 Web API Application Extensions NuGet package implement the Swagger functionality, making addition of WebApiTest.html file obsolete.
The Xamarin project can import the Swagger metadata file of the Web API project to create views, view models, and toolkit folders. A Xamarin application can also be scaffolded from the Swagger Metadata. For more information, refer to the Xamarin Cross-Platform App Developer Guide.
Procedure 1 - Adding the RESTful Web Service Project
In Solution Explorer, right-click the solution node, click Add, and select New Project....
In the Create a new project dialog box, do the following:
Notes:
Select C# or All Languages from the Language list.
Select Windows or All Platforms from the Platform list.
The ePortal templates are not displayed if other values are selected.
Select ePortal Presentation from the Project Type list.
The ePortal Presentation templates are displayed.
Do any one of the following to select the template:
From the templates list, select Web API Application, and then click Next.
Enter Web API Application in the search option, select the template from the search result, and then click Next.
Optionally, change the Project name, Location, and Framework, and click Create.
Notes:
If you do not select a desired Framework, a default Framework version is selected.
For information on selecting the .NET version, refer to Multi-Targeting Issues.
In Solution Explorer, right-click the new presentation project name and select Add Unisys ePortal Data Source Reference.
The Add Unisys ePortal Data Source Reference Dialog box appears. For more information, refer to Adding Unisys ePortal Data Source Reference.
Select the desired data source project and click OK.
Click Build and select Build Solution.
In Solution Explorer, right-click the new presentation project and select Add then select New Scaffolded Item.
The Add Scaffold dialog opens.
Select Unisys Web API Controller for ePortal Data Source, then click Add.
The Scaffold Unisys Web API Controller for ePortal Data Source Dialog opens.
Notes:
For compatibility with previous versions of ePortal, select Unisys Web API Controller for ePortal Data Source as Controller Scaffolder.
To make use of the enhanced routing options, select Unisys Data Source Web API Controller Version 2 as Controller Scaffolder.
Complete the dialog as described in the help reference.
Procedure 2- Preparing to use the Presentation Project
To prepare to use a RESTful Web Service application project, do the following:
Modify the Web.config file if required. The Web.config file is preconfigured with the keys and values. The following IncludeMessageTypeField key is set to false by default. You can change it to true if needed.
Key | Description | Value |
IncludeMessageTypeField | Boolean Key. If set to true, the MessageType filed will be included in the request and response schema. | false |
Procedure 3- Testing
Refer to Testing a Presentation Project.
Next Step
Continue to Staging a Presentation Project.