Skip to main content

HTTP Attributes

4/22/26About 2 min

HTTP Attributes

HTTP attributes are used to define the HTTP request method, path, and basic configuration.

Execution Order

Pre-execution order:

Parameter value validation → IApiActionAttribute → IApiParameterAttribute → IApiReturnAttribute → IApiFilterAttribute

Post-execution order:

IApiReturnAttribute → Return value validation → IApiFilterAttribute

Attribute Placement

[IApiFilterAttribute] // Filter applied to all methods in the interface
[IApiReturnAttribute] // ReturnAttribute applied to all methods in the interface
public interface DemoApiInterface
{
    [IApiActionAttribute]
    [IApiFilterAttribute] // Filter applied to this method
    [IApiReturnAttribute] // ReturnAttribute applied to this method
    Task<HttpResponseMessage> DemoApiMethod([IApiParameterAttribute] ParameterClass parameterClass);
}

HTTP Method Attributes

HttpHostAttribute

Use the HttpHost attribute when the request domain is a known constant.

[HttpHost("http://localhost:5000/")] // Applies to all methods under the interface
public interface IUserApi
{   
    Task<User> GetAsync(string id);

    [HttpHost("http://localhost:8000/")] // Overrides the HttpHost declared on the interface   
    Task<User> PostAsync(User user);
}

HttpGetAttribute

GET request:

public interface IUserApi
{   
    [HttpGet("api/users/{id}")] // Supports null, absolute or relative paths
    Task<User> GetAsync(string id);
}

HttpPostAttribute

POST request:

public interface IUserApi
{
    [HttpPost("api/users")] // Supports null, absolute or relative paths
    Task<User> PostAsync([JsonContent] User user);
}

HttpPutAttribute

PUT request:

public interface IUserApi
{
    [HttpPut("api/users")] // Supports null, absolute or relative paths
    Task<User> PutAsync([JsonContent] User user);
}

HttpDeleteAttribute

DELETE request:

public interface IUserApi
{
    [HttpDelete("api/users")] // Supports null, absolute or relative paths
    Task<User> DeleteAsync([JsonContent] User user);
}

HttpPatchAttribute

PATCH request:

public interface IUserApi
{
    [HttpPatch("api/users/{id}")]
    Task<UserInfo> PatchAsync(string id, JsonPatchDocument<User> doc);
}

var doc = new JsonPatchDocument<User>();
doc.Replace(item => item.Account, "laojiu");
doc.Replace(item => item.Email, "laojiu@qq.com");

HttpHeadAttribute

HEAD request:

public interface IUserApi
{
    [HttpHead("api/users/{id}")] // Supports null, absolute or relative paths
    Task<HttpResponseMessage> HeadAsync(string id);
}

HttpOptionsAttribute

OPTIONS request:

public interface IUserApi
{
    [HttpOptions("api/users")] // Supports null, absolute or relative paths
    Task<HttpResponseMessage> OptionsAsync();
}

Request Header Attributes

HeaderAttribute

Constant value request header:

public interface IUserApi
{   
    [Header("headerName1", "headerValue1")]
    [Header("headerName2", "headerValue2")]
    [HttpGet("api/users/{id}")]
    Task<User> GetAsync(string id);
}

Use parameter value as request header:

public interface IUserApi
{
    [HttpGet("api/users/{id}")]
    Task<User> GetAsync(string id, [Header] string headerName1);
}

HeadersAttribute

Use parameter value key-value pairs as request headers:

public interface IUserApi
{
    [HttpGet("api/users/{id}")]
    Task<User> GetAsync(string id, [Headers] CustomHeaders headers);

    [HttpGet("api/users/{id}")]
    Task<User> Get2Async(string id, [Headers] Dictionary<string,string> headers);
}

public class CustomHeaders
{
    public string HeaderName1 { get; set; }
    public string HeaderName2 { get; set; }
}

Other Attributes

TimeoutAttribute

Constant value request timeout duration:

public interface IUserApi
{   
    [Timeout(10 * 1000)] // Timeout duration is 10 seconds
    [HttpGet("api/users/{id}")]
    Task<User> GetAsync(string id);
}

Use parameter value as timeout duration, supports numeric types (milliseconds) or TimeSpan:

public interface IUserApi
{
    [HttpGet("api/users/{id}")]
    Task<User> GetAsync(string id, [Timeout] int timeoutMs);
    
    [HttpGet("api/users/{id}")]
    Task<User> GetAsync2(string id, [Timeout] TimeSpan timeout);
}

BasicAuthAttribute

Basic authentication:

public interface IUserApi
{
    [BasicAuth("username", "password")]
    [HttpGet("api/users/{id}")]
    Task<User> GetAsync(string id);
}

CacheAttribute

Request result caching:

public interface IUserApi
{
    [Cache(10 * 1000)] // Cache for 10 seconds
    [HttpGet("api/users/{id}")]
    Task<User> GetAsync(string id);
    
    [Cache(10 * 1000, IncludeHeaders = "Authorization,X-Token")] // Cache key includes request headers
    [HttpGet("api/users/{id}")]
    Task<User> GetWithHeadersAsync(string id);
}

HttpCompletionOptionAttribute

Indicates the request completion option to control response content reading behavior:

public interface IUserApi
{
    [HttpCompletionOption(HttpCompletionOption.ResponseHeadersRead)]
    [HttpGet("api/stream")]
    Task<Stream> GetStreamAsync();
}

UriAttribute

Use parameter value as request URI. Can only decorate the first parameter, and can be a relative or absolute URI:

public interface IUserApi
{
    [HttpGet]
    Task<User> GetAsync([Uri] Uri uri);
}

PathQueryAttribute

Use parameter value key-value pairs as request URL path parameters or query parameters. For general type parameters, PathQueryAttribute is implicitly applied when no attribute is specified:

public interface IUserApi
{   
    [HttpGet("api/users/{id}")]
    Task<User> GetAsync([PathQuery] string id);
}