Singleton Sub-resources

This pattern handles scenarios where a specific collection of data might change independently of the parent, have different security requirements, or simply might be too large to store directly as part of the resource.

Why should we use a singleton sub-resource?

SIZE OR COMPLEXITY

If a component will potentially become larger than all other pieces of a resource combined, it may make sense to separate that component from the resource. For example, if you have an API that stores large binary objects (like Amazon's S3), it would be unusual to store the binary data itself alongside the metadata about the object.

SECURITY

For example, you might have an API that represents employee data in a company, but the compensation information attached to each employee is likely to be much more highly restricted than more common things such as the employee's nickname, hometown, and telephone number.

VOLATILITY

there are often scenarios where specific components of a resource have unusual access patterns. In particular, if there is a component that is updated much more frequently than the other components on a resource, keeping these together could lead to a significant amount of write contention, which could ultimately lead to write conflicts.

As a result, it would make sense to separate the frequently changing location information from the other metadata so that updates can be done independently.

Trade-offs

Atomicity

One side effect of this is that there is no longer a way for us to interact with both the resource and the sub-resource together. In other words, we don’t have a way to atomically interact with both the parent resource and the sub-resource at the same time.

Exactly one sub-resource

Unlike a traditional subcollection that can contain many sub-resources of the same type, once we’ve adopted his pattern there can only ever be one instance of this specific sub-resource.

Exercises

How big does attribute data need to get before it makes sense to split it off into a separate singleton sub-resource? What considerations go into making your decision?

Size or complexity, security, and volatility.

Why do singleton sub-resources only support two of the standard methods (get and update)?

Singleton sub-resources simply exist by virtue of their parent existing. In other words, just as there’s no need to explicitly create properties on a resource.

Just as creating a parent resource causes a singleton sub-resource to be created, deleting that parent resource must also delete the singleton sub-resource.

Why do singleton sub-resources support a custom reset method rather than repurposing the standard delete method to accomplish the same goal?

Since deleting causes the sub-resource to act primarily like a property and not like a separate resource.

Why can't singleton sub-resources be children of other singleton sub-resources in the resource hierarchy?

There really isn’t any value added in having one singleton act as a parent to another.

Summary

Singleton sub-resources are hybrids between properties and resources, storing data that is inherent to a resource but in a separate isolated location.
Data might be separated from a resource into a singleton sub-resource for a variety of reasons, such as size, complexity, separate security requirements, or differing access patterns and the resulting volatility.
Singleton sub-resources support the standard get and update methods, but they should never be created or deleted and therefore should not support the standard create or delete methods.
Singleton sub-resources should generally also support a custom reset method, which restores the resource's attributes to their default states.
Singleton sub-resources should be attached to a parent resource, and that resource should not, itself, be another singleton sub-resource.