trellispark Core API Controllers

This article outlines the structure of Core API controllers. There will be a sample API with an explanation of purpose. Trellispark API controllers all follow the same structure.

To begin with, the class must be defined as a controller. This is done by inheriting the ControllerBase class, adding the APIController attribute, and adding a route. Fortunately the route can be calculated from the class name. Trellispark controllers are named according to purpose with a “Controller” suffix.

namespace Namespace
{
    [ApiController]
    [Route("[controller]")]
    public class PurposeController : ControllerBase
    {

The class requires a constructor. The constructor sets the configuration path and sets the parameters for the IDatabase interface.

public PurposeController(IConfiguration configuration)
        {
            Configuration = configuration;
            DB = IDatabase.SelectClient(Configuration);
        }

Each trellispark has a single endpoint. The route is consistent for all controllers. 3 status codes are permitted:

• 200OK – When the API passes the payload to the background logic. Whether that passes or fails, the response should be a 200 Ok and include the updated payload.
• 400BadRequest – If the payload is an incorrect structure and the API can’t validate the model state, the request is a bad request and should be returned.
• 500InternalServerError – If the API fails to connect to the database for any reason, an internal server error should be returned.

[HttpPost]
        [Route("CallAPI")]
        [ProducesResponseType(StatusCodes.Status200OK)]
        [ProducesResponseType(StatusCodes.Status400BadRequest)]
        [ProducesResponseType(StatusCodes.Status500InternalServerError)]
        public async Task<IActionResult> Call(Type Payload)

First, the IDatabase interface needs to be validated to ensure that the database connection is possible. Second, the model state of the payload type needs to be validated to ensure that the API has the correct object. Third, the database connection must be established.

try
            {
                if (DB != null)
                {
                    if (ModelState.IsValid)
                    {
                        if(await DB.Connect(Guid.Empty, Guid.Empty, "Command"))
                        {

After that, the API should call a second class to perform whatever logic is required. After which, the payload should be returned with an OK status. The following are the return statuses for the different checks.

                        }
                        else
                        {
                            Payload.ErrorMessage = "Invalid Session";
                            return Ok(Payload);
                        }
                    }
                    else
                    {
                        await AppInsights.Log(1, "PurposeController.Call.BadRequest", "", myDB);
                        return BadRequest();
                    }

                }
                else
                {
                    await AppInsights.Log(1, "PurposeController.Call.No Database Client", "", null);
                    return StatusCode(500);
                }