REST Principles

Learning objectives#

• Explain resources, URIs and representations
• Design URLs with nouns, not verbs
• Use HTTP methods for actions
• Explain why REST APIs are stateless

Explanation#

A resource is a thing your API exposes: a customer, an order, a product. Each has a URI: /api/customers/5.

URLs are nouns, usually plural. The action comes from the HTTP method: GET reads, POST creates, PUT replaces, PATCH updates part, DELETE removes. /api/getCustomer?id=5 is RPC style, not REST.

Relationships are expressed by nesting: /api/customers/5/orders is “the orders of customer 5”. Keep nesting to one level.

Stateless: every request carries everything the server needs (including the auth token). The server keeps no session between requests, so any server in a farm can answer — which is how APIs scale.

A representation is the format of the data, usually JSON. Clients ask with the Accept header; Web API 2 can also return XML unless you remove that formatter.

Use status codes to report outcomes (201 Created, 404 Not Found) instead of returning 200 with an error message inside.

Syntax#

1✓ GET    /api/customers            list customers
2✓ GET    /api/customers/5          one customer
3✓ POST   /api/customers            create a customer
4✓ GET    /api/customers/5/orders   orders of customer 5
5✗ GET    /api/getAllCustomers
6✗ POST   /api/deleteCustomer?id=5

Code example: A RESTful customers controller#

1using System.Web.Http;
2

3public class CustomerDto
4{
5    public int Id { get; set; }
6    public string Name { get; set; }
7}
8

9[RoutePrefix("api/customers")]
10public class CustomersController : ApiController
11{
12    // GET api/customers
13    [HttpGet, Route("")]
14    public IHttpActionResult GetAll()
15    {
16        return Ok(new[] { new CustomerDto { Id = 1, Name = "Asha" }, new CustomerDto { Id = 2, Name = "Ravi" } });
17    }
18

19    // GET api/customers/1
20    [HttpGet, Route("{id:int}")]
21    public IHttpActionResult GetById(int id)
22    {
23        return Ok(new CustomerDto { Id = id, Name = "Asha" });
24    }
25

26    // GET api/customers/1/orders   — a related resource
27    [HttpGet, Route("{id:int}/orders")]
28    public IHttpActionResult GetOrders(int id)
29    {
30        return Ok(new[] { new { OrderId = 101, CustomerId = id, Total = 1499.50m } });
31    }
32

33    // POST api/customers   — create; reply 201 with the new resource's URL
34    [HttpPost, Route("")]
35    public IHttpActionResult Create(CustomerDto customer)
36    {
37        customer.Id = 3;
38        return Created("api/customers/" + customer.Id, customer);
39    }
40}

GET  /api/customers           → 200 [{"Id":1,"Name":"Asha"},{"Id":2,"Name":"Ravi"}]
GET  /api/customers/1/orders  → 200 [{"OrderId":101,"CustomerId":1,"Total":1499.50}]
POST /api/customers {"Name":"Meera"}
                              → 201 Created, Location: api/customers/3, body {"Id":3,"Name":"Meera"}

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

1. [RoutePrefix("api/customers")] names the resource collection once for the whole controller.
2. GET on the collection lists customers; GET with an id returns one.
3. {id:int}/orders exposes a related resource under its parent.
4. POST on the collection creates a customer and answers 201 Created with a Location header pointing to it.
5. No URL contains a verb — the HTTP method says what to do.

Real-world use case#

Common mistakes#

Best practices#

• Plural nouns for collections (/api/products)
• One level of nesting at most
• Let HTTP methods carry the action
• Return meaningful status codes and Location headers

Remember this#

Practice exercise#

1GET    /api/posts
2GET    /api/posts/{id}
3POST   /api/posts
4PUT    /api/posts/{id}
5DELETE /api/posts/{id}
6GET    /api/posts/{id}/comments
7POST   /api/posts/{id}/comments

Mini quiz#

Want more? Practise all ASP.NET Web API MCQs · ASP.NET Web API interview questions

Related topics#

My notes#

Saved in this browser.