REST API for System Design

Is this a valid REST endpoint?
POST /events/create

No, because create is a verb. Action oriented language is not allowed in REST endpoints. Only nouns (resources)

Get all events

GET /events

get a specific event

GET /event/{id}

get available tickets for a specific event

GET /events/{id}/tickets

What are the HTTP Methods (5)

GET - retrieve data 

PUT - idempotent Update/replace 

POST - create data

PATCH - partial update 

DELTE - remove date

Path Params Purpose 

GET /events/{id}

• Specify which resource you are working with.

• Use when we want to specify the resource we want to use.

Query Params Purpose

GET /events?city=NYC&date=2025-01-01

• When you need to (optionally) filter a resource.

Request Body Purpose

• Send data when youre creating or updating a resource. 

POST /events 

{

title,

description 

}

Structure of a REST response 

1. the http status code 

2. The response body (usually JSON)

Pagination

a way for an API to send large results in smaller pieces (pages) using query parameters, instead of returning everything in one response.

GET /users?page=2&limit=10

Page=2 being used by the backend to calculate offset, limit=10 is used to limit the number of rows returned.

HTTP Status codes (10 basic ones)

200 - Success

201 - Success , Created 

301 - Permanent Redirect 

302 - Temporary Redirect 

400 - Bad Request 

401 - Not authenticated 

403 - Forbidden 

404 - Not Found 

500 - Server Error 

503 - Service Unavailable 

Offsets in Pagination

is the number of rows the database should skip first before it starts returning results.

In this example:
GET /users?page=2&limit=10

Page=2 , is used to calculate the offset in the backend.

Step-by-step

1. Read query params:

   • page = 2

   • limit = 10

2. Compute the offset:

offset = (page - 1) * limit
       = (2 - 1) * 10
       = 10

3. Build the SQL using LIMIT and OFFSET:

SELECT *
FROM users
ORDER BY id
LIMIT 10 OFFSET 10;

• LIMIT 10 → return 10 rows (the page size)

• OFFSET 10 → skip the first 10 rows (these were page 1)

So, page=2 is used only to figure out how many rows to skip. It tells the database, “skip the first 10 users, then give me the next 10.”

Cursor pagination

used when data changes a lot (lots of new writes), so instead of using page numbers, the API returns a cursor (a pointer to the last item you saw) and the next request asks for items after that cursor, which avoids skipping or duplicating items when new rows are inserted.

Example

GET /events?cursor=123&limit=25

• cursor=123 → “The last event I saw had an ID (or timestamp, etc.) of 123. Give me the next events after that one.”

• limit=25 → “Return up to 25 events after that cursor.”

SELECT *
FROM events
WHERE id > 123
ORDER BY id
LIMIT 25;

offset pagination (page based) vs cursor pagination

• Offset pagination: “skip N rows, then return the next M.”

• Cursor pagination: “start after this specific item, return the next M.”