Create your own Storefront endpoint

Configured Commerce provides RESTful web services from the Storefront. The web services provide endpoints, which map to entities such as Product and Category. Each endpoint maps to a Web API controller with a name like "ProductsV1Controller". The endpoint "api/v1/products/{productId}" maps to one of the ProductsV1Controller.Get methods and returns data for a specific product. In addition to the standard endpoints, you can create your own endpoints to operate on an existing or new entity. The walk-through below will create a Web API controller that returns some text. Much of the setup is not specific to Configured Commerce but uses the same setup for some Web API tutorials.

Preconditions

• Knowledge of Web API
• Visual Studio installed
• Configured Commerce SDK installed

Steps

Create a Web API Controller

1. In Visual Studio, open the Configured Commerce solution.
2. In your Extensions project, add a new class and name it "TestV1Controller". This is the standard naming convention for Web API controllers used by the Storefront. The "Test" portion of the name is the name of the entity, usually in plural form. The "V1" portion of the name indicates the version of the endpoint. In this case, this is the first version.
3. In the new class, inherit from the BaseApiController class. The BaseApiController class implements the ApiController provided by Web API. This is the first step towards making your controller accessible via a REST request. The BaseApiController does not have an empty constructor so you will need to implement a constructor to pass in any dependencies.

public class TestV1Controller : BaseApiController
{
    public TestV1Controller(
        ICookieManager cookieManager)
        : base(cookieManager)
    {
    }
}

4. Decorate the class with the [RoutePrefix] attribute. In the constructor, pass "api/v1/test" as the first argument. This is the route you will use to access any endpoints in the controller. This is the standard route format for Storefront endpoints used by Configured Commerce. The "api" portion of the route indicates that the endpoint is part of the Storefront API. The "v1" portion of the route indicates the version of the endpoint. In this case, this is the first version. The "test" portion of the route is the pluralized name of the entity. Another example is "api/v1/products", where the entity is "Product".

[RoutePrefix("api/v1/test")]
public class TestV1Controller : BaseApiController

5. In the body of the controller, declare a method named "Get" that accepts a Guid parameter named "productId". The response type should be IHttpActionResult or Task depending on whether or not the method is asynchronous.

public async Task<IHttpActionResult> Get()
{
}

6. Decorate the method with the [Route] and [ResponseType] attribute. In the constructor for the ResponseType attribute, pass typeof(string), since you are only returning a string.

[Route]
[ResponseType(typeof(string))]
public async Task<IHttpActionResult> Get()
{
}

7. Inside the method, return the string "test" inside an HTTP response. This is just an example. However, executing a handler chain within an endpoint method is common practice. All of the standard Web API controllers in B2B Commerce follow this practice.

[Route]
[ResponseType(typeof(string))]
public async Task<IHttpActionResult> Get()
{
    return this.Ok("test");
}

8. Build the solution.

Now you can make a request to your website, using "api/v1/test" as the path. This request should map to the controller you added and return the string you specified.

Storefront API Conventions

Web API controller are named using a convention, like "ProductsV1Controller". The "Products" portion of the name is the pluralized name of the entity. The "V1" portion of the name indicates the version of the endpoint. In this case, this is the first version.

Endpoint routes use a standard format, like "api/v1/products". The "api" portion of the route indicates that the endpoint is part of the Storefront API. The "v1" portion of the route indicates the version of the endpoint. In this case, this is the first version. The "products" portion of the route is the pluralized name of the entity.

Conclusion

In addition to the standard RESTful endpoints, you can create your own endpoints to operate on an existing or new entity. Endpoints require a Web API controller and are configured using much of the standard configuration provided by Web API. However, Configured Commerce provides some naming and route conventions that help organize the endpoints and make them easier to discover. This is just the first step in creating your own endpoint. After receiving the request, all of the standard Web API controllers in Configured Commerce hand over control to a handler chain. Creating a new or using an existing handler chain would be the next step in creating a usable Storefront endpoint.