ServiceStack: Using a single route to perform multiple business processes on a resource

Question

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:

1. Are we thinking about this incorrectly? Is there a better way to model this in a RESTful way?
2. 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?

Answer 1

What about /api/widgets/{id}/inspection? If you PUT it you could start the inspection, and if you GET it you could get the inspection status.

If you have more inspections running concurrently (with the transactions you mention), one could envision a schema where you POST to /api/widgets/{id}/inspections in order to create a new inspection at /api/widgets/{id}/inspections/{id}/. Here you can GET to view status, DELETE to cancel and so forth.

If you would like to determine the URL based on the message body, one idea is to have a /api/widgets/{id}/transactions resource, where you can POST a message. This resource could parse the body and return a 201 with a referral to /api/widgets/{id}/inspections/{id}/ if the body requested an inspection, or to /api/widgets/{id}/cleanings/{id}/ if the body requested a cleaning.

This are just some ideas. By the way, you might want to look at RESTify DayTrader for some inspiration.