Web API

ASP.NET Web API is a framework that was designed by Microsoft specifically to provide HTTP services that can be used with a wide range of clients. Its ability to easily define HTTP access routes and JSON handling makes it perfect for use with Editor.

Installation

The first step to using the Editor libraries in your Web API project is to include a reference to the DataTables-Editor-Server.dll, which provides all the classes and methods required. If you haven't already please follow the Installation instructions to include the DLL and also set up the database connection.

To complete the installation, add a using statement to the files where you will be using the Editor components (typically the model and controller):

using DataTables;

Controller attributes

WebAPI 2 provides a number of attributes that are used by the ApiController class. These attributes are instructions to the framework for how each controller method is exposed to the web and how it can be accessed.

There are three attributes that we are specifically interested in for Editor:

• Route() - defines the URL that the controller method can be accessed by. Note that this is attribute based routing, introduced in Web API 2. Conventional routing can also be used with Editor, although attribute based is often more convenient.
• HttpGet - allow the method to be accessed through an HTTP GET request - this is used by DataTables for loading the table's data.
• HttpPost - allow the method to be accessed through an HTTP POST request - this is used by Editor for create, edit and delete actions.

A typical controller for Editor might look like:

public class StaffController : ApiController
{
    [Route("api/staff")]
    [HttpGet]
    [HttpPost]
    public IHttpActionResult Staff()
    {
        var request = HttpContext.Current.Request;
        var settings = Properties.Settings.Default;

        using (var db = new Database(settings.DbType, settings.DbConnection))
        {
            var response = new Editor(db, "staff")
                .Model<StaffModel>()
                .Field(new Field("start_date")
                    .Validator(Validation.DateFormat(
                        Format.DATE_ISO_8601,
                        new ValidationOpts { Message = "Please enter a date in the format yyyy-mm-dd" }
                    ))
                    .GetFormatter(Format.DateSqlToFormat(Format.DATE_ISO_8601))
                    .SetFormatter(Format.DateFormatToSql(Format.DATE_ISO_8601))
                )
                .Process(request)
                .Data();

            return Json(response);
        }
    }
}

Where:

• Lines 3-5: Define the HTTP access options (GET and POST to api/staff).
• Line 6: The controller method with the FormDataCollection object that contains the data from the request.
• Line 8: The static HttpContext.Current.Request object is used to get information about the request (specifically the GET and POST parameters from the client-side). We store this in a variable for easy access on line 15.
• Line 9: Create variable to easily access database connection properties - this is not required, you can access this information from any other location that you might have it in your application.
• Line 11: Create a new Database instance in an using statement
• Line 13: Created a new Editor instance using the database staff.
• Line 14: Uses the StaffModel to define the fields
• Lines 15-18: Add a validator for the start_date field. Other fields can also have suitable validators added
• Lines 19-20: Use get and set formatters for the date field
• Line 21: Processes the data
• Line 22-24: Get the JSON response and return it to the client.

Models

For information about the models used for the Model() method, please refer to the getting started model documentation.

Next steps

There is of course a lot more that you can do with the Editor libraries, although you will typically apply the basics shown in this article every time. To expand your use of Editor, consider the following topics:

• Validators
• Formatters
• Joins