Learn how to design REST API with a real world example. We build an OTP based auth API with /signup, /login, /send-otp and /validate-otp features.
Problem statement:
Design the auth flow apis (signup, login, etc) for an OTP based user authentication. Assume OTP will be created and presented to users upon a successful login.
API Signature:
- URL
- Request Method
- Request Headers
- Request Body
- Response Status code
- Response Headers
- Response Body
Signup API:
- URL
- https://<name>.com/signup
- Will this be the URL on browser?
- Can we have same URL for UI and backend?
- https://<name>.com/api/signup or https://api.<name>.com/signup Are we missing anything?
- Versioning of APIs
- Path or via headers
- https://<name>.com/api/v1/signup or via request headers
- Request method: GET, PUT, POST, DELETE, PATCH, OPTIONS
- Which method should we use here?
- POST
- POST vs PUT? Idempotency
- Request Headers:
- Content Type: application/json
- any others?
- Request Body: Form Data, XML, JSON, i.e. Content Type
- JSON body:
- {
- "email": "foo@bar.com",
- "password": "supersecret", // plaintext password, yikes!
- "phone": "+91-9876543210"
- }
- Logic on server side?
- Validate request body
- Insert record in DB
- Handle errors
- Response Status code: 2xx, 3xx, 4xx, 5xx
- 200 ok or
- 201 created
- Response Headers:
- Content Type if we are sending any content back
- Any other headers?
- Response Body:
- Empty body or
- Some useful content (user id?)
Login API:
- URL https://<name>.com/api/v1/login
- Request method: POST
- Request Headers:
- Content Type: application/json
- any others?
- Request Body:
- JSON body:
- {
- "email": "foo@bar.com",
- "password": "supersecret", // plaintext password, yikes!
- }
- Logic on server side?
- Validate request body
- Check email and password combination
- Handle errors
- Create a token and send token back to user. Why?
- Response Status code: 2xx, 3xx, 4xx, 5xx
- 200 ok
- 4xx client side errors (validation of email, invalid credentials or unauthorized)
- 5xx server side errors (DB down so not able to login the user)
- Response Headers:
- Content Type if we are sending any content back
- Any other headers?
- Return a time limited token in headers
- Why do we need this? Let's come back to it when we talk about validate OTP API
- Response Body:
- Empty body or
- Send OTP as part of response?
- When do we actually send the OTP to user? Is it a UI triggered action? Or a "side-effect" of successful login
Send OTP API:
- URL https://<name>.com/api/v1/send-otp
- Request method: POST
- Request Headers:
- Token received from Login API reponse. Why?
- any others?
- Request Body:
- Empty body or
- Should we send phone number to send OTP to?
- Logic on server side?
- Validate token from headers
- Figure out phone number from token
- Sent OTP, store OTP in some storage for validation
- Response Status code: 2xx, 3xx, 4xx, 5xx
- 200 ok
- 4xx client side errors (invalid token, i.e. unauthorized)
- 5xx server side errors (Third party SMS vendor down, DB down, etc. so not able to send OTP the user)
- Response Headers:
- None that I can think of
- Response Body:
- Empty body
Validate OTP API:
- URL https://<name>.com/api/v1/validate-otp
- Request method: POST, or GET. Any query params?
- Request Headers:
- Token received from Login API reponse. Why?
- any others?
- Request Body:
- JSON body
- {
- "otp": "123456"
- }
- Logic on server side?
- Validate token
- Check token and OTP combination are correct
- Handle errors
- Response Status code: 2xx, 3xx, 4xx, 5xx
- 200 ok
- 4xx client side errors (invalid token, i.e. unauthorized, invalid otp, expired otp, etc.)
- 5xx server side errors (DB down so not able to validate OTP)
- Response Headers:
- None that I can think of
- Response Body:
- Empty body
Do you see any challenges/unknowns?
- Token before and after OTP validation is same. Is it okay? What problems can it cause?
- What if user requests for OTP multiple times? (both legit and abuser use case)
- Where do we store OTPs, Tokens?
- Can this API be used by both web and mobile?
