501 HTTP Status Code in ASP.NET Core Web API

Back to: ASP.NET Core Web API Tutorials

501 HTTP Status Code in ASP.NET Core Web API

In this article, I will discuss how to Return the 501 Not Implemented HTTP Status Code in an ASP.NET Core Web API Application with Examples. Please read our previous article on how to Return the 500 Internal Server HTTP Status Code in ASP.NET Core Web API with Examples.

What is 501 HTTP Status Code?

The 501 HTTP Status Code stands for “Not Implemented.” This status code indicates that the server does not support the functionality required to fulfill the request. It is generally used when the server recognizes the request method but lacks the ability to fulfill it.

What is the 501 HTTP Status Code in ASP.NET Core Web API?

In ASP.NET Core Web API, a 501 HTTP Status Code indicates that the server understands the request method (like GET, POST, PUT), but the server’s configuration or the current state of the application does not allow it to support the action required by the request. This could be due to missing implementation or a server configuration that does not support the functionality. If this is not clear at the moment, don’t worry; we will explain it with a few examples.

What are the Common Reasons for a 501 HTTP Status Code?

The following are some of the common reasons why a 501 HTTP Status Code might be returned:

  • Unsupported HTTP Method: The requested method is not supported by the server or the API endpoint.
  • Feature Not Implemented: The API endpoint or functionality is not yet implemented or is under development.
  • Routing Issues: Check if a specific route is active and return a 501 status code with details if it is not.
  • Misconfiguration: There might be a misconfiguration in the server or API settings, leading to unsupported operations.
How Do We Return a 501 HTTP Status Code in ASP.NET Core Web API?

Returning a 501 HTTP status code in ASP.NET Core Web API is straightforward and can be achieved using various approaches, depending on the specific requirements of your application. The 501 status code is used to indicate that the server either does not support the requested functionality or that the functionality has not been implemented yet.

Adding Keys in AppSettings.json file:

Please modify the AppSettings.json file as follows. Here, we are adding a few keys, which we will use inside the action method. Based on the condition, we might return the 501 HTTP Status Code to the client.

{
  "SupportedMethods": {
    "AllowPost": false
  },
  "Features": {
    "BetaFeatureEnabled": false
  },
  "Routing": {
    "UseSpecialRoute": false
  },
  "CriticalSettings": {
    "ApiKey": null
  }
}
Returning 501 HTTP Status Code Using StatusCode Method

In ASP.NET Core Web API, we can return a 501 HTTP status code by using the StatusCode method of the ControllerBase class. This method allows us to specify the status code and an optional value to be returned in the response body. To better understand, please modify the Sample Controller as follows. The following code is self-explained. Please read the comment lines for a better understanding:

using Microsoft.AspNetCore.Mvc;

namespace ReturnTypeAndStatusCodes.Controllers
{
    // Define the route for the controller as 'api/sample'
    [Route("api/[controller]")]
    [ApiController]
    public class SampleController : ControllerBase
    {
        private readonly IConfiguration _configuration;

        // Constructor to initialize the configuration dependency
        public SampleController(IConfiguration configuration)
        {
            _configuration = configuration;
        }

        // Scenario 1: Unsupported HTTP Method
        // Check if POST requests are temporarily disabled and return 501 status code if they are.
        [HttpPost("unsupported-method")]
        public IActionResult UnsupportedMethod()
        {
            // Retrieve the configuration value that indicates if POST is allowed
            bool isPostAllowed = _configuration.GetValue<bool>("SupportedMethods:AllowPost", true);

            // Check if POST requests are temporarily disabled
            if (!isPostAllowed)
            {
                // Prepare detailed information for the 501 response
                var detail = new
                {
                    Message = "POST method is currently disabled on this endpoint.",
                    SupportContact = "support@example.com",
                    Timestamp = DateTime.UtcNow
                };

                // Return 501 status code with detailed information
                return StatusCode(501, detail);
            }

            // Simulate a typical POST handling logic and return success response
            return Ok(new { Status = "Success", Description = "POST method is accepted and processed." });
        }

        // Scenario 2: Feature Not Implemented
        // Check if a specific feature is ready for use and return 501 status code if it is not.
        [HttpGet("feature-not-implemented")]
        public IActionResult FeatureNotImplemented()
        {
            // Retrieve the configuration value that indicates if the feature is enabled
            bool isFeatureReady = _configuration.GetValue<bool>("Features:BetaFeatureEnabled", false);

            // Check if the feature is not ready
            if (!isFeatureReady)
            {
                // Prepare detailed information for the 501 response
                var detail = new
                {
                    Message = "Feature is under development and not available.",
                    ExpectedReleaseDate = "2024-10-11"
                };

                // Return 501 status code with detailed information
                return StatusCode(501, detail);
            }

            // Simulate a response for a ready feature and return success response
            return Ok("Beta feature is fully operational.");
        }

        // Scenario 3: Routing Issues
        // Check if a specific route is active and return 501 status code if it is not.
        [HttpGet("routing-check")]
        public IActionResult RoutingCheck()
        {
            // Retrieve the configuration value that indicates if the special route is active
            bool isSpecialRouteActive = _configuration.GetValue<bool>("Routing:UseSpecialRoute", false);

            // Check if the special route is not active
            if (!isSpecialRouteActive)
            {
                // Prepare detailed information for the 501 response
                var detail = new
                {
                    Message = "The requested endpoint is not routed correctly.",
                    HelpUrl = "http://example.com/api-help/routing-issues"
                };

                // Return 501 status code with detailed information
                return StatusCode(501, detail);
            }

            // Return success response indicating the routing is correctly configured
            return Ok("Routing is correctly configured for this endpoint.");
        }

        // Scenario 4: Misconfiguration
        // Check if a critical configuration value is set and return 501 status code if it is missing.
        [HttpGet("configuration-check")]
        public IActionResult ConfigurationCheck()
        {
            // Retrieve the critical configuration value
            string? criticalConfig = _configuration.GetValue<string>("CriticalSettings:ApiKey", null);

            // Check if the critical configuration value is missing
            if (string.IsNullOrEmpty(criticalConfig))
            {
                // Prepare detailed information for the 501 response
                var detail = new
                {
                    Message = "Critical API key is not configured.",
                    Administrator = "admin@example.com"
                };

                // Return 501 status code with detailed information
                return StatusCode(501, detail);
            }

            // Return success response indicating all critical configurations are set properly
            return Ok("All critical configurations are set properly.");
        }
    }
}
Real-Time Use Cases of 501 HTTP Status Code:

Let us understand the Real-Time Use Cases of a 501 HTTP Status Code in ASP.NET Core Web API by comparing it with our example.

Unsupported HTTP Method:

Check if POST requests are temporarily disabled and return a 501 status code with details if they are. Retrieves a configuration value to determine if POST is allowed. If not, return a 501 status code with a detailed message.

Imagine a payment processing API that handles sensitive transactions. Due to regulatory changes or temporary security concerns (like a detected vulnerability or ongoing maintenance), the API may need to disable certain methods, such as POST, which initiate transactions. The ability to dynamically disable these methods without deploying new code can be crucial.

For example, A bank’s API temporarily disables the POST method on transaction endpoints during a system upgrade to prevent new transactions from being initiated while databases are updated. This ensures consistency and prevents issues like double posting or data corruption.

Feature Not Implemented:

Check if a specific feature is ready for use and return a 501 status code with details if it is not. Retrieves a configuration value to determine if the feature is enabled. If not, return a 501 status code with a detailed message, including the expected release date.

In software development, particularly in services offered over the web, new features are rolled out gradually. Sometimes, features are announced or documented before they are fully implemented. A toggle in the configuration could control the availability of such features, allowing for seamless activation once development and testing are completed.

Routing Issues:

Check if a specific route is active and return a 501 status code with details if it is not. Retrieves a configuration value to determine if the special route is active. If not, returns a 501 status code with a detailed message and a help URL.

For example, an e-commerce platform has a special promotional route that is only activated during certain sales events (like Black Friday). This route enables special APIs that handle increased load and specific discount logic. If a request is made to this route outside of the designated times, a 501 status code is returned, guiding users to a help page for more information.

Misconfiguration:

Check if a critical configuration value is set and return a 501 status code with details if it is missing. Retrieves a critical configuration value. If it is missing, return a 501 status code with a detailed message, including the administrator’s contact.

Critical settings, like API keys or environment variables, are essential for the operation of many systems. Missing or incorrectly set configurations can lead to significant functionality issues or security vulnerabilities.

For example, a video streaming service relies on a third-party API for metadata about movies and TV shows. The API key for this service is a critical configuration. If this key is missing, the service cannot fetch necessary data, significantly impacting functionality. The system checks for this key at runtime and returns a 501 error if it is not set, including contact information for the system administrator to resolve the configuration issues.

Return 501 HTTP Status Code using Custom ActionResult:

To return a 501 status code using a custom action result in ASP.NET Core Web API, we need to create a custom ActionResult class and use it in our controller. If returning a 501 Status Code is common across different actions or controllers, we can create a custom ActionResult to reuse the same. So, create a class file named NotImplementedResult.cs and then copy and paste the following code. The following code is self-explained. Please read the comment lines for a better understanding:

using Microsoft.AspNetCore.Mvc;
using System.Text.Json;
namespace ReturnTypeAndStatusCodes.Models
{
    // Custom action result class that represents a 501 Not Implemented HTTP response
    // Custom action result class must IActionResult and provide implementation for the ExecuteResultAsync method
    public class NotImplementedResult : IActionResult
    {
        // Field to hold the detailed information to be included in the response
        private readonly object _detail;

        // Constructor to initialize the detail field
        public NotImplementedResult(object detail)
        {
            _detail = detail; // Assign the provided detail to the private field
        }

        // Method to execute the result and write the response
        public async Task ExecuteResultAsync(ActionContext context)
        {
            // Serialize the detail object to a JSON string
            var json = JsonSerializer.Serialize(_detail);

            // Set the response content type to "application/json"
            context.HttpContext.Response.ContentType = "application/json";

            // Set the response status code to 501 Not Implemented
            context.HttpContext.Response.StatusCode = StatusCodes.Status501NotImplemented;

            // Write the JSON string to the response body
            await context.HttpContext.Response.WriteAsync(json);
        }
    }
}

The NotImplementedResult class implements IActionResult and is responsible for returning a 501 status code with a detailed message. It serializes the detailed information to JSON and writes it to the HTTP response with a status code of 501. Now, the above custom NotImplementedResult class can be used in your controllers to return a 501 status code with detailed information about why the request cannot be fulfilled. So, modify the Sample Controller to use the custom NotImplementedResult for returning 501 status codes as follows.

using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;

namespace ReturnTypeAndStatusCodes.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class SampleController : ControllerBase
    {
        private readonly IConfiguration _configuration;

        public SampleController(IConfiguration configuration)
        {
            _configuration = configuration;
        }

        // Scenario 1: Unsupported HTTP Method
        [HttpPost("unsupported-method")]
        public IActionResult UnsupportedMethod()
        {
            bool isPostAllowed = _configuration.GetValue<bool>("SupportedMethods:AllowPost", true);

            if (!isPostAllowed)
            {
                var detail = new
                {
                    Message = "POST method is currently disabled on this endpoint.",
                    SupportContact = "support@example.com",
                    Timestamp = DateTime.UtcNow
                };

                // Return custom 501 status code with detailed information
                return new NotImplementedResult(detail);
            }

            // Simulate a typical POST handling logic and return success response
            return Ok(new { Status = "Success", Description = "POST method is accepted and processed." });
        }

        // Scenario 2: Feature Not Implemented
        [HttpGet("feature-not-implemented")]
        public IActionResult FeatureNotImplemented()
        {
            bool isFeatureReady = _configuration.GetValue<bool>("Features:BetaFeatureEnabled", false);

            if (!isFeatureReady)
            {
                var detail = new
                {
                    Message = "Feature is under development and not available.",
                    ExpectedReleaseDate = "2024-10-11"
                };

                // Return custom 501 status code with detailed information
                return new NotImplementedResult(detail);
            }

            // Simulate a response for a ready feature and return success response
            return Ok("Beta feature is fully operational.");
        }

        // Scenario 3: Routing Issues
        [HttpGet("routing-check")]
        public IActionResult RoutingCheck()
        {
            bool isSpecialRouteActive = _configuration.GetValue<bool>("Routing:UseSpecialRoute", false);

            if (!isSpecialRouteActive)
            {
                var detail = new
                {
                    Message = "The requested endpoint is not routed correctly.",
                    HelpUrl = "http://example.com/api-help/routing-issues"
                };

                // Return custom 501 status code with detailed information
                return new NotImplementedResult(detail);
            }

            // Return success response indicating the routing is correctly configured
            return Ok("Routing is correctly configured for this endpoint.");
        }

        // Scenario 4: Misconfiguration
        [HttpGet("configuration-check")]
        public IActionResult ConfigurationCheck()
        {
            string? criticalConfig = _configuration.GetValue<string>("CriticalSettings:ApiKey", null);

            if (string.IsNullOrEmpty(criticalConfig))
            {
                var detail = new
                {
                    Message = "Critical API key is not configured.",
                    Administrator = "admin@example.com"
                };

                // Return custom 501 status code with detailed information
                return new NotImplementedResult(detail);
            }

            // Return success response indicating all critical configurations are set properly
            return Ok("All critical configurations are set properly.");
        }
    }
}

Now, each action method in the controller uses NotImplementedResult to return a 501 status code when appropriate. This approach centralizes the logic for handling 501 responses, making the controller code cleaner and more maintainable.

In the next article, I will discuss how to Return 503 Service Unavailable HTTP Status Code in ASP.NET Core Web API with Examples. In this article, I try to explain how to Return 501 Not Implemented Error HTTP Status Code in ASP.NET Core Web API. I hope you enjoy this article on “How to Return 501 Not Implemented Error HTTP Status Code in ASP.NET Core Web API.”

Leave a Reply

Your email address will not be published. Required fields are marked *