I'm trying to write up an API and struggling to figure out a nice way of adding custom actions to a resource. For example, in my User resource I want to have the actions enabled and disable, but within the usual blueprint grouping I can't add these under a group:
## User [/users/{id}]
### Update a User [PATCH]
...
### Delete a User [DELETE]
...
### Disable a User [PATCH]
....
Here, the Disable a User and Update a User both point to the same URL which isn't what I want. I want these to produce the URLs /users/{id} and /users/{id}/disable respectively.
Looking through other API source, others have done it without using named resources, which would give:
## /users/{id}
### Update a User [PATCH]
...
### Delete a User [DELETE]
...
## /users/{id}/disable
### Disable a User [PATCH]
...
Whilst I can use this approach, I'd prefer to use the first approach as it's cleaner when it gets rendered by most blueprinting tools.
Is there a way of having custom actions using the first approach, or does anyone else have a cleaner way of implementing the same kind of thing
In this example, because there are two different URLs, you actually will end up with two separate resources. One resource is a User resource, while the other is a Disable User resource. To organize these in your API Blueprint, you can group these resources together with a Resource Group.
# Group User Resources
## User [/users/{id}]
### Update a User [PATCH]
...
### Delete a User [DELETE]
...
## Disable User [/users/{id}/disable]
### Disable User [PATCH]
...
This allows you to have separate actions on separate URLs while keeping them tied together in your documentation.