Web Api design - Using Nouns vs verbs

Question

I have this design situation at work. We have a internal Web-Api application and a Asp.Net Web forms application(UI). The web-application is calling Web-Api to update a Contractor.

public Class Contractor {
    public string Id {get;set;}
    public string Name {get;set;}
    <<Ton of other Properties>>
    public string Status {get;set;}
}

Typically the UI app can update the complete contractor by sending in all the details, except for the status. A user can change the status to closed by clicking on a Special "Close" button on the screen. In this case the architect on the UI team doesn't want to send the complete contractor with status as closed. Also before a Contractor is closed there a a set of Business rules that need to be satisfied. So this is not a direct update.

So can we provide a route like "/api/Contractor/{id}/Close"? Isn't this against the RESTFul principle of not using Verbs in the nouns and dealing with Resources instead of actions. Can I make an exception in this case?

Answer 1

Isn't this against the RESTFul principle of not using Verbs in the nouns and dealing with Resources instead of actions.

No - REST doesn't care about how you spell your identifiers.

It's violates URI design guidelines, for exactly the reason you specify -- you are naming an entity (a noun) with a verb. HTTP is already giving you verbs, so you don't need them in the identifier.

The most common solution to this sort of problem is to create a resource that represents the specific noun you want to manipulate, for instance

/api/Contractor/{id}/status

Also before a Contractor is closed there a a set of Business rules that need to be satisfied.

This suggests that the resource that is being manipulated isn't a status, but an event or a command -- for example: ContractorDismissed, and the change to the status is a side effect.