Custom REST endpoint

New in Telligent Evolution Platform SDK 5.5.2

The Telligent CustomEndpoint sample project included in version 5.5.2 of the Telligent Evolution platform SDK was developed as a reference for implementing custom endpoints for REST v2 Web services. It provides an end-to-end example of everything needed to build and connect a custom REST endpoint - including registering routes, implementing a controller and actions, and registering the controller and action. In this article, you will find detailed implementation details of the sample application that will help you better understand the source code.

Telligent CustomEndpoint source code

The Telligent CustomEndpoint sample application is made up of several types of files:

Rest entity

The Foo.cs file is a custom entity that inherits from RestEntity<int>. This will be the object returned to the user and acted upon by the controller's actions. In many cases, this entity will be a representation of some sort of other internal class, in which case you'll want to map your internal class to the Rest Entity.

Route registrar

The FooRouteRegistrar.cs file contains the route registrar class that inherits BaseRouteRegistrar and registers the custom routes of the Foo controller with the RouteTable and the REST pipeline. An entry is made to register a route for each separate action that the Foo controller supports. In addition to building the route registrar, you must also map the registrar to IRegisterRoutes in the RestModule.config file.

Action requests and responses

There are request and response classes for every action supported by FooController: FooCreateRequest.cs, FooCreateResponse.cs, FooDeleteRequest.cs, FooDeleteResponse.cs, FooListRequest.cs, FooListResponse.cs, FooShowRequest.cs, FooShowResponse.cs, FooUpdateRequest.cs, and FooUpdateResponse.cs. Each request class defines the parameters the request accepts and inherits from RestRequest (or PagedRestRequest). Each response class defines what is included in the response sent back to the user and inherits from RestResponse. The classes themselves provide no functionality; they just define the structure of the requests and responses and wire up to the controller actions using the RestAction() attribute.

Controller and actions

The FooController.cs file contains the Foo controller with methods for each action that the Foo controller supports. Every REST controller has to implement IController. Every controller does not need to support each of the default actions: LIST, SHOW, CREATE, UPDATE and DELETE. Each of the action methods in the class provides a good example of how to convert a request into a response, how to handle errors, and what type of information to return.

The sample FooController is a simple example that returns static content. As such, all of the business logic is contained in the action methods' bodies. In real world scenarios, you'll want to do as little work as possible in the action methods and instead make calls to service classes to handle performing the business logic. The purpose of the action methods should be to collect the request information and pass a model back to the user. Everything that happens in between should be performed somewhere besides the controller.

Action registrar

The FooActionRegistar.cs file contains the action registrar that implements IRegisterActions and tells the REST framework that your custom assembly has a REST controller(s) inside it. In addition to building an action registrar, you must also map the registrar to IRegisterActions in the RestModule.config file.

Deploying the Telligent CustomEndpoint to your site

To deploy the Foo endpoint to your site:

1. Compile the CustomEndpoint project.
2. Copy the Telligent.Rest.CustomEndpoint.dll file to your Web site's bin folder.
3. Update the RestModule.config file adding a mapping from IRegisterRoutes to your route registrar class.
4. Update the RestModule.config file adding a mapping from IRegisterActions to your action registrar class.

Additional notes

• For any REST endpoints to function properly, the site must have the REST API enabled. You can enable the REST API via the Control Panel: Site Administration > Site Configuration > Manage REST API.
• For any REST endpoint to function properly, the accessing user must have permissions allowing him/her to access the REST API. The Site - Access Web Services permission must be assigned to a role which includes that user. You can manage permissions via the Control Panel: Membership Administration > Members and Roles > Manage Site Roles.