A RESTful API for

Refer to Resources and their Identifiers in URL

Example Template: 

/Resource/Resource_Identifier/Sub_Resource/Sub_Resource_Identifier

Sample Review URL

/Consumer/{consumer_id}/review/{review_id}

/Dealer/{dealer_id}/review/{review_id}

Have a common set of Resource(and/or Sub Resources)

/Consumer/{consumer_id}/reviews

Use HTTP verbs to accomplish different operations:

GET  /Consumer/123/reviews

For a Single Resource eg: A Review for a Consumer:

Base URL:

/Consumer/{consumer_id}/reviews/{review_id}

Http Verbs:

GET /Consumer/123/reviews/456

- Give me a Review(id 456) for Consumer(id 123)

PUT /Consumer/123/reviews/456

- Update A Consumer(id 123) Review (id 456)

DELETE /Consumer/123/reviews/456

- Delete a Consumer Review (456)

POST /Consumer/123/reviews/456

- ERROR: POST cannot be done for a resource already created

Use QueryString parameters to filter reviews

1. Show only featured reviews:

GET /Consumer/{consumer_id}/reviews?featured=true

2. Show review with Service

GET /Consumer/{consumer_id}/reviews?filterBy=service

3. Show reviews for New Car

GET /Consumer/{consumer_id}/reviews?filterBy=newcar

Using a Simple Major.Minor Scheme

http://services.cars.com/CRRS/1.2/Consumer/123/reviews/

Sometimes a consumer is only interested in a specific field set

eg: Mobile consumers where Payload size is a concern

Use Query String for field filtration

/Consumer/{consumer_id}/reviews?fields=Reviews.OverallRating,Reviews.location

For Pagination, again use Query String parameters

/Consumer/{consumer_id}/reviews?start=50&count=20

1. JSON

2. XML

By Default will return responses in JSON format

1. Use Format type at the end of the URL

/Consumer/123/reviews.json

2. Use Accept Header

Accept: application/json

3. Use a type query parameter to indicate response type

/Consumer/123/reviews?responseType=json

Since a search is not tied to a specific resource, use a search url with a query parameter at the base URL level:

http://services.cars.com/CRS/search?status=VAL

http://services.cars.com/CRS/search?status=PEN

http://services.cars.com/CRS/search?zip=60630&make=toyota

Use HTTP Return codes

200 - OK 

- Review Retreival was successful

- Review was POSTed

- Review was DELETEd

400 - Bad Request

- Request from client was syntactically bad

404 - Resource Not Found

- Review was not found

- Consumer was not found

500 - Internal Server Error

- Service failure

Additional Code Refinements:

201 - Created

- A review was created

- A response was created

- A feedback was created