REST API / URL设计用于具有复数/发布方法的资源

Question

Say, for example, I had a REST api url design with "Customer" as a resource.

Now, I want to be able to list all customers, find a specific customer by ID or Email address
Also, I want to be able to add a new customer...

Are these example URIs right?
Or should I be doing it another way..?

/customer/1234
get customer with id 1234

/customer/email/john@smith.com
get customer with email address

[POST]
/customer/
creates a new customer

/customers/
list all customers (notice pluralization)

Answer 1

In my experience RESTful APIs use a single resource path that is plural. The idea is that you have customers and when you want to interact with a customer you are interacting with the customers resource in general.

GET /customers to get a list of customers.

POST /customers to create a new customer.

GET /customers/:id to get a specific customer with a unique id. (Generally not an attribute of a customer like email )

GET /customers?email=bob@example.com to get customers with a specific attribute value.

Apigee has a blog post that covers pluralization that you might want to read.

Answer 2

If I was designing this API I would start with a generic hypermedia type like HAL and design a root representation that provides me access to the various scenarios you describe using links and uri templates.

eg

GET /api
=>
<resource>
   <link rel="urn:mycompany:customer" href=".../{id}"/>
   <link rel="urn:mycompany:customers" href="..."/>
   <link rel="urn:mycompany:customersearch" href="...{?email}"/>
</resource>

I have not filled in the actual URLs because from the perspective of the consumer of the API it really does not matter how those URLs are structured. Do whatever is easiest in you server framework. Don't worry if you get it wrong, you can change it later and your clients won't break because they should discover the URL from the root representation.

It is fairly common to assume that POSTing a customer to a collection of customers will create a new Customer, so you could just require your consumers to use that link. Or if you wish to be more explicit you could define a new link relation that provides a URL for creating Customers.

Answer 3

This is how I would do it:

/customer/1234

customer/john@smith.com or (if email not guaranteed to be unique) customers/search?email=john@smith.com

[POST] /customers/ (notice the plural, same as below)

[GET] /customers/

Cheers,

Ferenc

Answer 4

Why not be robust and enable both /customer and /customers?

GET /customer/1234 or /customers/1234 retrieves the same resource.

GET on /customer or /customers gives a list of all customers.

POST to /customer or /customers creates a new customer.