CodeByDay.ApiCache 1.0.0

Code By Day: API Cache

Adds a ServerCacheAttribute to intelligently cache responses on the server side.

Release Notes

1.0.0 First release

Usage Guide

Add the ServerCacheAttribute to your controller:

[ServerCache(Duration = 3600)]
public class MyController : Controller

And that's it! Your controller will now cache all requests for 3600 seconds (one hour)!

Controller Configuration

To configure the entire controller, modify the values the ServerCacheAttribute. All the attributes mentioned in the Method Configuration section are baked-in to the ServerCacheAttribute.

Implied Invalidations

If a controller is POSTed to, it will (by default) invalidate its cache. If more than the controller's cache needs to be invalidated, you can pass in the types for the other controllers to the ServerCacheAttribute constructor:

[ServerCache(typeof(MyOtherController), Duration = 3600)]
public class MyController : Controller

Method Configuration

If an individual method needs customization, you can append a DurationConfigurationAttribute, StatusCodeConfigurationAttribute, VerbConfigurationAttribute, or a DoNotCacheAttribute.

DurationConfigurationAttribute

The DurationConfigurationAttribute allows you to change how long a method is cached for.

StatusCodeConfigurationAttribute

The StatusCodeConfigurationAttribute allows you to specify the HTTP status codes which should be cached.

VerbConfigurationAttribute

The VerbConfigurationAttribute allows you to change the action on each verb: cache, don't cache, or invalidate existing cache. For example, if your endpoint is a POST, but should be cached, you can append the following attribute to the method:

[VerbConfigurationAttribute(Post = Cacheability.Cache)]

IEtagProvider

By default, ETags are generated by the time at which the response was generated. This can cause issues if your server's memory is cleared: the user will have a valid cached response, but the server will not know since that ETag is no longer in memory. You can add your own IEtagProvider attribute to override the ETag and use a more stable response.

IMPORTANT: If you create your own IEtagProvider attribute, you MUST put it before the ServerCacheAttribute:

[MyEtagProvider]
[ServerCache(Duration = 3600)]
public class MyController : Controller

An IEtagProvider attribute is also legal on a method. A method's attributes will be preferred over the controller's.

IKeyProvider

In order to avoid any possibility of cache collisions, the default IKeyProvider stores the query string and entire body as a string. This is how it identifies that two requests are the same. If your API generally receives requests with big bodies, you may consider creating your own IKeyProvider attribute to override this behavior and, perhaps, store a Hash of the body instead. You may also want to override the default behavior if you know two requests are equivalent without their bodies bing the same. An example would be { Name: "Joe", Age: 30 } and { Age: 30, Name: "Joe" }; the default handler will consider these two different requests, but a custom handler could notice that these are the same request and return the same key.

IMPORTANT: If you create your own IKeyProvider attribute, you MUST put it before the ServerCacheAttribute:

[MyKeyProvider]
[ServerCache(Duration = 3600)]
public class MyController : Controller

An IKeyProvider attribute is also legal on a method. A method's attributes will be preferred over the controller's.

IModifiedProvider

By default, the Last-Modified header is set to the time at which the response was generated. This is correct most of the time. However, if you have static files, you can create your own IModifiedProvider to read the write time on those static files and send that back instead.

IMPORTANT: If you create your own IModifiedProvider attribute, you MUST put it before the ServerCacheAttribute:

[MyModifiedProvider]
[ServerCache(Duration = 3600)]
public class MyController : Controller

An IModifiedProvider attribute is also legal on a method. A method's attributes will be preferred over the controller's.

Repo

Branches

The branches in this repo relate directly to the release they are building up to. Once a release has been made, the branch is no longer commited to. This effectively means there is no "master" branch: only releases.

Versioning

This project uses Semantic Versioning 2.0.0

I recommend editing your .csproj to force this Semantic Versioning. This example requires a version equal to or above 1.0.0 and disallows 2.0.0 or above.

<PackageReference Include="CodeByDay.ApiCache" Version="[1.0.0,2.0.0)" />