Rest API Design - OTP based Auth API

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?