Support HTTP caching

[evanp]

"As an ActivityPub API client developer, I want to know if the cached version of an object I have is the latest version, so I can save the time and resources of fetching the data again."

[evanp]

RFC 9111 covers the basics of HTTP caching.

I'm not sure it makes sense to define this from the client side -- a lot of client-side HTTP libraries handle this internally, and browser clients get access to the browser cache automatically.

It might be worthwhile to include some guidance for the server, though. For example:

• Sending ETag
• Sending Last-Modified
• Sending Vary
• Sending Cache-Control

[evanp]

One particular header that can be tough in ActivityPub is Last-Modified. When fetching an ActivityPub object, it's not unusual to include embedded objects, which may have different modification dates. For example, consider this Note:

{
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "https://notes.example/note/893D219C-8564-4F32-B6AD-5ECD3F0DA328",
    "type": "Note",
    "content": "<p>Hello, world.</p>",
    "to": "as:Public",
    "attributedTo": "https://notes.example/actor/1F6A11E8-513A-4EA3-AF46-D1654B9DC0E6",
    "published": "2026-03-18T01:00:00Z",
    "updated": "2026-03-18T02:00:00Z"
}

In this case, the Last-Modified header when fetching https://notes.example/note/893D219C-8564-4F32-B6AD-5ECD3F0DA328 should match the updated property, but in HTTP header format, Wed, 18 Mar 2026 02:00:00 GMT.

If the representation includes the attributedTo value as an embedded object, though, it becomes more complicated:

{
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "https://notes.example/note/893D219C-8564-4F32-B6AD-5ECD3F0DA328",
    "type": "Note",
    "content": "<p>Hello, world.</p>",
    "to": "as:Public",
    "attributedTo": {
        "id": "https://notes.example/actor/1F6A11E8-513A-4EA3-AF46-D1654B9DC0E6",
        "type": "Person",
        "name": "Greetsy Q. Greeterson",
        "to": "as:Public",
        "published": "2024-02-11T00:00:00Z",
        "updated": "2026-03-18T05:00:00Z"
    },
    "published": "2026-03-18T01:00:00Z",
    "updated": "2026-03-18T02:00:00Z"
}

In this case, an embedded object has been updated more recently than the base or source object. For the server, it's probably easiest to set the Last-Modified header to the updated timestamp of the main object, but for the client, it's probably more useful to know when the representation was changed. The ETag would probably change here, for most ETag algorithms, I think.

Given that embedded objects can be nested to almost arbitrary levels, determining which object in the tree was most recently changed, and if that change affected this representation, is a real hassle for the server.

It may actually be more performant to always refer to other objects with an URL. Although it requires another request to get the referred object, it simplifies caching, which might mean that the "extra" requests are actually cache hits instead.

[evanp]

It's also worth noting that HTTP caching really sucks for the federation protocol. Since we use Signature for client authentication, and since Signature changes with every request (because it includes the Date), we don't have an easy way to say that it's OK to cache things for a single user. Vary: Signature doesn't work.

[evanp]

If you're using #1 for authentication, then it's possible to use Vary: Authorization as a caching header. However, if the bearer token is short-lived, this might mean that the cache invalidates for the same user account. But that's probably better than nothing.

[evanp]

Cache-Control: private is probably always the best option. Even though there is a lot of so-called public data on the social web, it's actually "everyone but" access. Blocked users and servers are not allowed to fetch that content.