ServiceStack: Using a Single Route to Run Multiple Business Processes on a Resource

Question

My team is in the process of developing a REST API for an existing enterprise application that handles physical asset tracking.

Our domain model is quite complex, and when designing our routes we are faced with the problem of blocking.

Ideally, we would like each resource to support several business processes. But we cannot find a way to do this without increasing the resource URL to help the ServiceStack routing mechanism determine which DTO to use.

Here is an example. We keep a detailed history of transactions associated with widgets, and users can perform several types of actions on widgets that we represent using various types of transactions. For example, a widget can be checked or it can be cleared. Both are operations with /api/widget/{id} , but the first results are in a validation transaction, and the second is a maintenance transaction. We would 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 is not possible. Instead, it looks like we need to create two endpoints: /api/widgets/{id}/inspect and /api/widgets/{id}/clean or something like that.

This is not very RESTful, as it is not far from /api/cleanWidget . This is more a method call than updating a resource.

Another option we discussed is to create a single /api/transactions endpoint, since most API requests will result in a transaction. However, this will lead to the creation of a single monolithic endpoint, and users will need to figure out which of the dozens of possible data attributes to fill out for a given request type. It is also quite far from the use cases that will be programmed by our users. They care more about the physical entities with which they interact, and not about our behind-the-scenes implementation.

Two questions:

• Are we thinking about it wrong? Is there a better way to simulate this using RESTful?
• If our thinking sounds, is there a good way to use ServiceStack to examine the request body when deciding which DTO and service method to use when satisfying the request?

Answer 1

What about /api/widgets/{id}/inspection ? If you install it, you can start the inspection, and if you receive it, you can get the verification status.

If you have more checks performed at the same time (with the transactions you mention), you could imagine a scheme in which you send POST to /api/widgets/{id}/inspections to create a new check in /api/widgets/{id}/inspections/{id}/ . Here you can GET view the status, DELETE to cancel, etc.

If you want to define a URL based on the body of the message, one idea is to have a resource /api/widgets/{id}/transactions where you can send a POST message. This resource can analyze the body and return 201 with a referral to /api/widgets/{id}/inspections/{id}/ if the body requested a check or /api/widgets/{id}/cleanings/{id}/ if the body requested a cleanup.

These are just some of the ideas. By the way, you can take a look at RESTify DayTrader for some inspiration.