API Design – When to Use Nested Resources in a RESTful API

None of this is authoritative (as REST has no exact meaning). But from the original paper on REST a full (not ending in /) URL names a resource, while one ending in a slash '/' is a resource group (probably not worded like that).

A GET of a URL with a slash on the end is supposed to list the resources available.

GET http://example.com/dogs/          /* List all the dogs resources */

A PUT on a URL with a slash is supposed to replace all the resources.

PUT http://example.com/dogs/          /* Replace all the dogs resources */

A DELETE on a URL with a slash is supposed to delete all the resources

DELETE http://example.com/dogs/       /* Deletes all the dogs resources */

A POST on a URL with a slash is supposed to create a new resource can then be subsequently accessed. To be conformant the new resource should be in this directory (though lots of RESTful architectures cheat here).

POST http://example.com/dogs/        /* Creates a new dogs resource (notice singular) */

etc.

The wiki page on the subject seems to explain it well:

See example https://en.wikipedia.org/wiki/Representational_state_transfer#Applied_to_Web_services.

I highly recommend reading RESTful Webservices, especially the chapters on the difference between RESTful and RPC style web programming; and the chapters on resource discovery and how to deal with the apparent need for "verbs" (they are usually a different resource in disguise).

Converting an enquiry to a customer does not need a "convert" verb. You wouldn't delete the enquiry just because you create a customer and thus you are simply creating a customer with the information from the enquiry as input.

POST /users/{userId}/customers?enquiry={EnguiryId}

or simply

POST /users/{userId}/customers

with the enquiry information in the request body.

By the way, I use POST on customers because that is the way to do it if the server application is in control of the identifier generation. Only use PUT to create resources if the caller is the one determining the identifiers.

On a side note: have you considered the security and privacy issues relating to including /users/{UserId} in your URI's? Anybody can now start trying different userid's to get at information of different users of your application. You really should consider leaving them off your URI's and having them determined by the authentication information that should be send with each request (and possibly refreshed with each response).