What an API is and how REST APIs are designed: Backend Development (Beginner)

What is an API?

API means Application Programming Interface. It is a list of requests a program accepts and the answers it gives back. The app on your phone does not open the database itself. It talks to the backend through its API.

Think of it like this: An API is like a waiter in a restaurant. You do not walk into the kitchen. You read the menu (the API documentation), tell the waiter your order in a fixed way (a request), and the waiter brings back your food (a response). The kitchen can change its stoves, and you never notice, as long as the menu stays the same.

REST: resources as nouns

REST (REpresentational State Transfer) is a popular style for designing web APIs. In REST, every kind of data is a resource: users, products, orders. Each resource has a URL. The URL is a noun (a thing), and the HTTP method is the verb (the action).

Request	Action	Success code
GET /products	List all products	200
GET /products/42	Read product 42	200
POST /products	Create a new product	201
PUT /products/42	Replace product 42 completely	200
PATCH /products/42	Change some fields of product 42	200
DELETE /products/42	Delete product 42	204

A collection is the whole list (/products). An item is one member of it (/products/42). The number at the end is the id, a unique value that names one record. Related data can be nested: /users/42/orders means "the orders of user 42".

Good names and bad names

Avoid	Use instead	Why
GET /getUsers	GET /users	The method already says "get"
POST /createOrder	POST /orders	POST on a collection means create
GET /deleteUser?id=5	DELETE /users/5	GET must never change data
/user/5 and /orders	/users/5 and /orders	Use plural names everywhere, consistently
/orderItems or /Order_Items	/order-items	Small letters, words joined with hyphens

Tip: Simple rule: nouns in the URL, verbs in the method. If you are about to write a verb like get, create or delete in a URL, use the right method instead.

Filtering and versions

To filter, sort or page through a list, use the query string on the collection, not new URLs: GET /products?category=rice&maxPrice=200&sort=price&page=2. One URL, many options.

APIs change over time, but old apps on people's phones still call the old API. So many APIs put a version at the start of the path: /v1/products. When you must make a breaking change, you add /v2/products and keep /v1 working for a while.

javascript

function describe(method, path) {
  const parts = path.split('/').filter(Boolean); // ['products', '42']
  const isItem = parts.length === 2;
  return method + ' on ' + (isItem ? 'one ' + parts[0] + ' item (id ' + parts[1] + ')' : 'the ' + parts[0] + ' collection');
}

console.log(describe('GET', '/products'));     // GET on the products collection
console.log(describe('DELETE', '/products/42')); // DELETE on one products item (id 42)

Splitting the path tells you whether the request is about the whole collection or one item.

Careful: Do not change what an existing endpoint returns (renaming or removing fields) without a new version. Old app versions on users' phones will break, and you cannot force everyone to update.

What an API is and how REST APIs are designed

Explanation

What is an API?

REST: resources as nouns

Good names and bad names

Filtering and versions

Watch the lesson

In real life: The API behind a college results site

Practice (0/3 done)

Quick quiz

Read more (free)