Web API Thoughts 1 of 3 - Data Streaming

There are numerous articles written about ASP.NET Web API technology. A lot can be found in CodeProject (ASP.NET Web API), the ASP.NET Web API official web site, as well as additional places. The following series of articles will try to explain the technology by applying on Data Streaming, HTTPS and extending Web API documentation. The articles assume you have basic knowledge of C#, ASP.NET, OOP, ASP.NET MVC, REST service, IIS and some technical terms of .NET framework. With that being said, the articles will be presented with the following order.

 
public static void Register(HttpConfiguration config)
{
    // Web API configuration and services
    // Web API routes
     config.MapHttpAttributeRoutes();
    
     config.Routes.MapHttpRoute(name: "PhysicianApi",
                routeTemplate: "{controller}/{action}/{id}",
                defaults: new { id = RouteParameter.Optional });
}

[Route("physician/{speciality}/{physicianID}")]
public PhysicianBase GetPhysicianBySpeciality(string speciality, int physicianID)
{
    // Todo : Process the request 
}

Once these pre-configuration are completed, it is easy to create and consume data stream Web API service. The first thing to do is to define the file streaming ApiController along with the necessary operations. As I stated earlier, the main methods of the file streaming service are download and upload. But, it also contains other methods related to file streaming.

/// <summary>
/// File streaming API
/// </summary>
[RoutePrefix("filestreaming")]
[RequestModelValidator]
public class StreamFilesController : ApiController
{
    /// <summary>
    /// Get File meta data
    /// </summary>
    /// <param name="fileName">FileName value</param>
    /// <returns>FileMeta data response.</returns>
    [Route("getfilemetadata")]
    public HttpResponseMessage GetFileMetaData(string fileName)
    {
        // .........................................
        // Full code available in the source control
        // .........................................

    }

    /// <summary>
    /// Search file and return its meta data in all download directories
    /// </summary>
    /// <param name="fileName">FileName value</param>
    /// <returns>List of file meta datas response</returns>
    [HttpGet]
    [Route("searchfileindownloaddirectory")]
    public HttpResponseMessage SearchFileInDownloadDirectory(string fileName)
    {
        // .........................................
        // Full code available in the source control
        // .........................................
    }

    /// <summary>
    /// Asynchronous Download file
    /// </summary>
    /// <param name="fileName">FileName value</param>
    /// <returns>Tasked File stream response</returns>
    [Route("downloadasync")]
    [HttpGet]
    public async Task<HttpResponseMessage> DownloadFileAsync(string fileName)
    {
        // .........................................
        // Full code available in the source control
        // .........................................
    }

    /// <summary>
    /// Download file
    /// </summary>
    /// <param name="fileName">FileName value</param>
    /// <returns>File stream response</returns>
    [Route("download")]
    [HttpGet]
    public HttpResponseMessage DownloadFile(string fileName)
    {
        // .........................................
        // Full code available in the source control
        // .........................................
    }

    /// <summary>
    /// Upload file(s)
    /// </summary>
    /// <param name="overWrite">An indicator to overwrite a file if it exist in the server</param>
    /// <returns>Message response</returns>
    [Route("upload")]
    [HttpPost]
    public HttpResponseMessage UploadFile(bool overWrite)
    {
        // .........................................
        // Full code available in the source control
        // .........................................
    }

    /// <summary>
    /// Asynchronous Upload file
    /// </summary>
    /// <param name="overWrite">An indicator to overwrite a file if it exist in the server</param>
    /// <returns>Tasked Message response</returns>
    [Route("uploadasync")]
    [HttpPost]
    public async Task<HttpResponseMessage> UploadFileAsync(bool overWrite)
    {
        // .........................................
        // Full code available in the source control
        // .........................................
    }
}

The Download service method works first by checks the requested file name existence in the desired file path. If file is not found,it returns an error response object saying "file is not found". If it succeeds, it reads the content as bytes and attaches to the response object as an application/octet-stream MIMI content type.

/// <summary>
/// Download file
/// </summary>
/// <param name="fileName">FileName value<param>
/// <returns>File stream response<returns>
[Route("download")]
[HttpGet]
public HttpResponseMessage DownloadFile(string fileName)
{
    HttpResponseMessage response = Request.CreateResponse();
    FileMetaData metaData = new FileMetaData();
    try
    {
        string filePath = Path.Combine(this.GetDownloadPath(), @"\", fileName);
        FileInfo fileInfo = new FileInfo(filePath);

        if (!fileInfo.Exists)
        {
            metaData.FileResponseMessage.IsExists = false;
            metaData.FileResponseMessage.Content = string.Format("{0} file is not found !", fileName);
            response = Request.CreateResponse(HttpStatusCode.NotFound, metaData, new MediaTypeHeaderValue("text/json"));
        }
        else
        {
            response.Headers.AcceptRanges.Add("bytes");
            response.StatusCode = HttpStatusCode.OK;
            response.Content = new StreamContent(fileInfo.ReadStream());
            response.Content.Headers.ContentDisposition = new ContentDispositionHeaderValue("attachment");
            response.Content.Headers.ContentDisposition.FileName = fileName;
            response.Content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
            response.Content.Headers.ContentLength = fileInfo.Length;
        }
    }
    catch (Exception exception)
    {
        // Log exception and return gracefully
        metaData = new FileMetaData();
        metaData.FileResponseMessage.Content = ProcessException(exception);
        response = Request.CreateResponse(HttpStatusCode.InternalServerError, metaData, new MediaTypeHeaderValue("text/json"));
    }
    return response;
}

The Upload service method works on top of a multipart/form-data MIMI content type. First it checks the HTTP request content type is a type of multipart. If it succeeds, it compares the content length to the maximum allowed file size to be uploaded. If it succeeds, it starts to upload the request content to the desired location. When the operation is completed, it notifies the user with appropriate response message. The code fragment that performs upload is shown below.

/// <summary>
/// Upload file(s)
/// </summary>
/// <param name="overWrite">An indicator to overwrite a file if it exist in the server.</param>
/// <returns>Message response</returns>
[Route("upload")]
[HttpPost]
public HttpResponseMessage UploadFile(bool overWrite)
{
    HttpResponseMessage response = Request.CreateResponse();
    List<FileResponseMessage> fileResponseMessages = new List<FileResponseMessage>();
    FileResponseMessage fileResponseMessage = new FileResponseMessage { IsExists = false };

    try
    {
        if (!Request.Content.IsMimeMultipartContent())
        {
            fileResponseMessage.Content = "Upload data request is not valid !";
            fileResponseMessages.Add(fileResponseMessage);
            response = Request.CreateResponse(HttpStatusCode.UnsupportedMediaType, fileResponseMessages, new MediaTypeHeaderValue("text/json"));
        }

        else
        {
            response = ProcessUploadRequest(overWrite);
        }
    }
    catch (Exception exception)
    {
        // Log exception and return gracefully
        fileResponseMessage = new FileResponseMessage { IsExists = false };
        fileResponseMessage.Content = ProcessException(exception);
        fileResponseMessages.Add(fileResponseMessage);
        response = Request.CreateResponse(HttpStatusCode.InternalServerError, fileResponseMessages, new MediaTypeHeaderValue("text/json"));

    }
    return response;
}

/// <summary>
/// Asynchronous Upload file
/// </summary>
/// <param name="overWrite">An indicator to overwrite a file if it exist in the server.<param>
/// <returns>Tasked Message response</returns>
[Route("uploadasync")]
[HttpPost]
public async Task<HttpResponseMessage> UploadFileAsync(bool overWrite)
{
    return await new TaskFactory().StartNew(
       () =>
       {
           return UploadFile(overWrite);
       });
}

/// <summary>
/// Process upload request in the server
/// </summary> 
/// <param name="overWrite">An indicator to overwrite a file if it exist in the server.</param>
/// </returns>List of message object</returns>
private HttpResponseMessage ProcessUploadRequest(bool overWrite)
{
    // .........................................
    // Full code available in the source control
    // .........................................
}

The client app that calls the download and upload file method is a console app. The app consumes the file streaming Web API service through HttpClient and related classes. Basically the download file code creates a download HTTP request object with a proper file name and sends the request to the server.

/// <summary>
/// Download file
/// </summary>
/// <returns>Awaitable Task object</returns>
private static async Task DownloadFile()
{
    Console.ForegroundColor = ConsoleColor.Green;
    Console.WriteLine("Please specify file name  with extension and Press Enter :- ");
    string fileName = Console.ReadLine();
    string localDownloadPath = string.Concat(@"c:\", fileName); // the path can be configurable
    bool overWrite = true;
    string actionURL = string.Concat("downloadasync?fileName=", fileName);

    try
    {
        Console.WriteLine(string.Format("Start downloading @ {0}, {1} time ",
            DateTime.Now.ToLongDateString(),
            DateTime.Now.ToLongTimeString()));


        using (HttpClient httpClient = new HttpClient())
        {
            httpClient.BaseAddress = baseStreamingURL;
            HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, actionURL);

            await httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead).
                ContinueWith((response)
                    =>
                {
                    Console.WriteLine();
                    try
                    {
                        ProcessDownloadResponse(localDownloadPath, overWrite, response);
                    }
                    catch (AggregateException aggregateException)
                    {
                        Console.ForegroundColor = ConsoleColor.Red;
                        Console.WriteLine(string.Format("Exception : ", aggregateException));
                    }
                });
        }
    }
    catch (Exception ex)
    {
        Console.ForegroundColor = ConsoleColor.Red;
        Console.WriteLine(ex.Message);
    }
}


/// <summary>
/// Process download response object
/// </summary>
/// <param name="localDownloadFilePath">Local download file path</param>
/// <param name="overWrite">An indicator to overwrite a file if it exist in the client.</param>
/// <param name="response">Awaitable HttpResponseMessage task value</param>
private static void ProcessDownloadResponse(string localDownloadFilePath, bool overWrite,
    Task<HttpResponseMessage> response)
{
    if (response.Result.IsSuccessStatusCode)
    {
        response.Result.Content.DownloadFile(localDownloadFilePath, overWrite).
            ContinueWith((downloadmessage)
                =>
            {
                Console.ForegroundColor = ConsoleColor.Green;
                Console.WriteLine(downloadmessage.TryResult());
            });
    }
    else
    {
        ProcessFailResponse(response);
    }
}

Notice the code above. The HttpClient object sends the request and waits the response to send only the response header (HttpCompletionOption.ResponseHeadersRead), not the entire response content of the file. Once the response header is read, it performs the necessary validation on the content and if it succeeds, the actual file downloading method will be executed.

And here is the code that calls the upload file streaming Web API service method. Similar to download method, it creates a request object with a multipart form data content type and sends the request to the server. The content is validated and sent to server to be processed further.

/// <summary>
/// Upload file
/// </summary>
/// <returns>Awaitable task object</returns>
private static async Task UploadFile()
{
    try
    {
        string uploadRequestURI = "uploadasync?overWrite=true";

        MultipartFormDataContent formDataContent = new MultipartFormDataContent();

        // Validate the file and add to MultipartFormDataContent object
        formDataContent.AddUploadFile(@"c:\nophoto.png");
        formDataContent.AddUploadFile(@"c:\ReadMe.txt");

        if (!formDataContent.HasContent()) // No files found to be uploaded
        {
            Console.ForegroundColor = ConsoleColor.Red;
            Console.Write(formDataContent.GetUploadFileErrorMesage());
            return;
        }
        else
        {
            string uploadErrorMessage = formDataContent.GetUploadFileErrorMesage();
            if (!string.IsNullOrWhiteSpace(uploadErrorMessage)) // Some files couldn't be found
            {
                Console.ForegroundColor = ConsoleColor.Red;
                Console.Write(uploadErrorMessage);
            }

            HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, uploadRequestURI);
            request.Content = formDataContent;

            using (HttpClient httpClient = new HttpClient())
            {
                Console.ForegroundColor = ConsoleColor.Green;
                Console.WriteLine(string.Format("Start uploading @ {0}, {1} time ",
                DateTime.Now.ToLongDateString(),
                DateTime.Now.ToLongTimeString()));

                httpClient.BaseAddress = baseStreamingURL;
                await httpClient.SendAsync(request).
                      ContinueWith((response)
                          =>
                          {
                              try
                              {
                                  ProcessUploadResponse(response);
                              }
                              catch (AggregateException aggregateException)
                              {
                                  Console.ForegroundColor = ConsoleColor.Red;
                                  Console.WriteLine(string.Format("Exception : ", aggregateException));
                              }
                          });
            }
        }
    }
    catch (Exception ex)
    {
        Console.ForegroundColor = ConsoleColor.Red;
        Console.WriteLine(ex.Message);
    }
} 

/// <summary>
/// Process download response object
/// </summary>
/// <param name="response">Awaitable HttpResponseMessage task value</param>
private static void ProcessUploadResponse(Task<HttpResponseMessage> response)
{
    if (response.Result.IsSuccessStatusCode)
    {
        string uploadMessage = string.Format("\nUpload completed @ {0}, {1} time ",
                    DateTime.Now.ToLongDateString(),
                    DateTime.Now.ToLongTimeString());
        Console.ForegroundColor = ConsoleColor.Green;
        Console.WriteLine(string.Format("{0}\nUpload Message : \n{1}", uploadMessage,
            JsonConvert.SerializeObject(response.Result.Content.ReadAsAsync<List<FileResponseMessage>>().TryResult(), Formatting.Indented)));
    }
    else
    {
        ProcessFailResponse(response);
    }
}

The data streaming project is also consists of extension classes and methods which are not explicitly explained in the article. Download the source code and explore it.

What's Next

The next section explains about Working with HTTPS

References

• http://en.wikipedia.org/wiki/Representational_state_transfer
• http://en.wikipedia.org/wiki/Request-response
• http://www.ietf.org/rfc/rfc2616
• http://msdn.microsoft.com/en-us/library/hh849329(v=vs.108).aspx
• http://www.iis.net/configreference/system.webserver/security/requestfiltering/requestlimits
• http://www.ASP.NET/web-api/
• http://technet.microsoft.com/en-us/library/bb727008.aspx

History and GitHub Version

• WebAPI Thoughts @ GitHub
• Update on Nov 4, 2014
• Update on Nov 18, 2014
• Update on Nov 20, 2014
• Update on Oct 18, 2015 - Article code format issue