My team is in the process of designing a REST API for an existing enterprise application that handles tracking of physical assets.
Our domain model is pretty complex, and we're hitting a blocking issue while designing our routes.
Ideally, we'd like each resource to support multiple business processes. But we can't find a way to do that without extending the resource's URL to help ServiceStack's routing engine figure out which DTO to use.
Here's an example. We keep a detailed history of transactions that involve widgets, and users can perform multiple types of actions on a widget that we represent with different types of transactions. For example a widget
could be inspected, or it could be cleaned. Both are operations against /api/widget/{id}
, but the first results in an inspection transaction and the second a maintenance transaction. We'd really like to create different DTOs that use the same route, /api/widget/{id}
, and have the correct DTO selected based on the request body.
This doesn't appear to be possible. Instead, it's looking like we need to create two endpoints: /api/widgets/{id}/inspect
and /api/widgets/{id}/clean
, or something similar.
That doesn't feel very RESTful, since it's not far from /api/cleanWidget
. It's more of a method call than an update to a resource.
Another option we've discussed is creating a single /api/transactions
endpoint, since most requests to the API will result in a transaction being created. However, this would result in a single, monolithic endpoint, and users would have to figure out which of dozens of possible data attributes they need to populate for a given type of request. It's also pretty far removed from the use cases that our users will be programming for. They care more about the physical entities they're interacting with, not our behind-the-scenes implementation.
Two questions:
- Are we thinking about this incorrectly? Is there a better way to model this in a RESTful way?
- If our thinking is sound, is there a good way to use ServiceStack to consider the request body when determining which DTO and service method to use when satisfying the request?