Create custom REST API endpoints

Workflow Studio supports extending the default EmpowerID REST API by allowing you to create your own custom API endpoints using the API Item Type. In Workflow Studio, Item Types are templated class libraries that provide a base starting point for building an implementation of a specific type. The API Item Type provides a starting point for creating a REST API endpoint.

This tutorial walks through the basics of creating an API endpoint that can be consumed in EmpowerID.

In this tutorial, you will learn how to do the following:

Create API project in Workflow Studio

1. In Workflow Studio, right-click the folder where you want to create the API project and select New Extension or Library > API (.NET Framework).
   
   

   Open

   

   
   
   Workflow Studio generates a stub for the API project and opens the base class for it in the C# Editor.
   
   

   Open

   

   
   
   

2. Click the Save above the C# Editor.
   
   

   
   
   

3. Name the API HelloAPI and click Save.
   
   

   
   
   Workflow Studio generates a stub for the new API class.
   
   

   
   
   Next, add a controller to the API to receive incoming HTTP requests and send the response back.

Add a controller

1. In the Code Tree, right-click the project and select Add New Controller.
   
   

   
   
   

2. Name the controller HelloAPI and click OK.
   
   

   
   
   Workflow Studio creates the new class and opens it in the C# Editor. Notice the class is decorated with the RBACProtectedAttribute and the RelatedApplicationAttribute.
   
   RBACProtectedAttribute — This attribute is used to secure access to the endpoint using the RBAC authorization framework. It should not be removed.
   RelatedApplicationAttribute — This attribute specifies the parent application for the endpoint, which is set to the EmpowerID Web application by default (GUID). You can alter the parent to specify another application by setting the value of the GUID to that application. This allows you to publish APIs for users specific to the applications they use. For example, you could publish an API for customers or partners who use a CRM application that is registered in EmpowerID. By relating the endpoint to the CRM application, your customers or partners only need to have access to the application to consume the endpoint.
   
   

   
   
   Additionally, notice that Workflow Studio generated the following classes in addition to the controller:
   A route for routing incoming HTTP requests to a specific action method on the controller
   A model to represent data
   
   

3. Close the project.
   
   Next, we will open the API project in Visual Studio and add logic to the controller and route.

Open the project in Visual Studio

1. In the Source Control tree of Workflow Studio, locate the API project and double-click it.
   
   

   
   
   You should see the project open as a solution in Visual Studio.
   
   

    

2. Open the HelloAPI class and add a new method to the class that returns a string named GetHelloString().
   
   

   public dynamic GetHelloString(dynamic data) { string helloString = "Hello API!"; return helloString; }

    

3. Open the HelloAPIController class and add the following code to create the stub for a new anonymous method named GetHelloAPIString(). Decorate the method with ApiAllowAnonymous to allow anonymous access and use GET as the HTTP method.
   
   

   [ApiAllowAnonymous] [HttpGet] public IHttpActionResult GetHelloAPIString(HelloAPIInputModel model) { var results = _implInstance.GetHelloString(model); // Return object as JSON return Json((object)results); }

    

4. Open the HelloAPIRoutes.cs file.
   
   Notice the GetRouteMaps() method defines a dictionary of routeMaps. Notice the default GetRouteMaps() method defines a dictionary of routeMaps. You can use this default method or replace the commented out code with your routes. We do this in this example.
   
   

   public IEnumerable<KeyValuePair<string, MapRouteModel>> GetRouteMaps() { var routeMaps = new Dictionary<string, MapRouteModel>(); /* Your routes go here! Below is an example - var map = new MapRouteModel(); map.Name = 'mapApi'; map.Route = 'services/v1/itshop/maps/{id}'; map.Defaults = new { controller = 'Maps',action = 'GetMapsByMapsGUID', id = RouteParameter.Optional }; routes['mapApi'] = map; */ return routeMaps; }

5. Edit the default route so that it looks like the following code.
   
   

    

6. Compile the class library.
   
   

   
   
   

7. Click Close to close the Operations log. If you see any errors, check your code and then compile the class library again.
   
   

   
   
   

8. Compile and publish the class library.
   
   

   
   
   

9. Select No when prompted about restarting services.

10. Reset IIS.

The custom API end point is now available for you to consume. You can test the end point in Postman by following the procedure outlined in the Getting an Access Token and Creating a Person topics. When specifying the URL, append the base URL for your environment with the route, the controller and the method; e.g., https://{FQDN_OF_Your_EmpowerID_Web_Server}/api/TestCustomAPIEndPoint/v1/TestCustomAPIEndPointController/GetCustomString.

See Also

Add OAuth Scopes to API Endpoints