chinmay185 · July 18, 2025 18:46 · Apr 24, 2022 · Apr 24, 2022 · Apr 24, 2022
diff --git a/...pi-design-with-otp-based-auth-example.txt → ...api-design-with-otp-based-auth-example.md b/...pi-design-with-otp-based-auth-example.txt → ...api-design-with-otp-based-auth-example.md
@@ -4,7 +4,7 @@
 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:
+# API Signature:
     - URL
     - Request Method
     - Request Headers
@@ -13,7 +13,7 @@ API Signature:
     - Response Headers
     - Response Body
 
-Signup API:
+## Signup API:
 - URL
     - https://silkystore.com/signup
         - Will this be the URL on browser?
@@ -35,12 +35,14 @@ Signup API:
 
 - Request Body: Form Data, XML, JSON, i.e. Content Type
     - JSON body:
+    ```
       {
-      "email": "[email protected]",
-      "password": "supersecret", // plaintext password, yikes!
-      "phone": "+91-9876543210"
+        "email": "[email protected]",
+        "password": "supersecret", // plaintext password, yikes!
+        "phone": "+91-9876543210"
       }
-
+    ```
+    
 - Logic on server side?
     - Validate request body
     - Insert record in DB
@@ -59,7 +61,7 @@ Signup API:
     - Some useful content (user id?)
 
 
-Login API:
+## Login API:
 - URL https://silkystore.com/api/v1/login
 
 - Request method: POST
@@ -70,11 +72,13 @@ Login API:
 
 - Request Body:
     - JSON body:
+    ```
       {
-      "email": "[email protected]",
-      "password": "supersecret", // plaintext password, yikes!
+        "email": "[email protected]",
+        "password": "supersecret", // plaintext password, yikes!
       }
-
+    ```
+    
 - Logic on server side?
     - Validate request body
     - Check email and password combination
@@ -98,7 +102,7 @@ Login API:
     - 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:
+## Send OTP API:
 - URL https://silkystore.com/api/v1/send-otp
 
 - Request method: POST
@@ -128,7 +132,7 @@ Send OTP API:
     - Empty body
 
 
-Validate OTP API:
+## Validate OTP API:
 - URL https://silkystore.com/api/v1/validate-otp
 
 - Request method: POST, or GET. Any query params?
@@ -139,9 +143,11 @@ Validate OTP API:
 
 - Request Body:
     - JSON body
-      {
-      "otp": "123456"
-      }
+    ```
+     {
+        "otp": "123456"
+     }
+    ```
 
 - Logic on server side?
     - Validate token
@@ -160,7 +166,7 @@ Validate OTP API:
     - Empty body
 
 
-Do you see any challenges/unknowns?
+## 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?

diff --git a/gistfile1.txt → ...pi-design-with-otp-based-auth-example.txt b/gistfile1.txt → ...pi-design-with-otp-based-auth-example.txt
diff --git a/gistfile1.txt b/gistfile1.txt
@@ -0,0 +1,167 @@
+
+# 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://silkystore.com/signup
+        - Will this be the URL on browser?
+        - Can we have same URL for UI and backend?
+
+    - https://silkystore.com/api/signup or https://api.silkystore.com/signup Are we missing anything?
+        - Versioning of APIs
+        - Path or via headers
+        - https://silkystore.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": "[email protected]",
+      "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://silkystore.com/api/v1/login
+
+- Request method: POST
+
+- Request Headers:
+    - Content Type: application/json
+    - any others?
+
+- Request Body:
+    - JSON body:
+      {
+      "email": "[email protected]",
+      "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://silkystore.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://silkystore.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?