From 9fae6face014685a03c22611aba3894c760c4618 Mon Sep 17 00:00:00 2001
From: Shihaam Abdul Rahman <shihaam@shihaam.me>
Date: Sat, 31 May 2025 21:17:52 +0500
Subject: [PATCH] updated docs

---
 README.md | 58 ++++++++++++++++++++++++++++---------------------------
 1 file changed, 30 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index b1a3b3c..2fd1073 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,7 @@
 # MAC Address Vendor Lookup API
-
 A FastAPI service that identifies network device manufacturers from MAC addresses using a three-tier lookup strategy for optimal performance and reliability.
 
 ## Features
-
 - **Multi-format MAC address support**: Accepts various formats (with/without separators)
 - **Partial MAC lookup**: Works with full addresses or just the first 6 digits (OUI)
 - **Three-tier lookup strategy**:
@@ -13,18 +11,18 @@ A FastAPI service that identifies network device manufacturers from MAC addresse
 - **Standardized output**: Returns MAC addresses in dash-separated format
 
 ## Supported MAC Address Formats
-
 All of these formats are accepted:
 - `000000` (OUI only)
 - `00:00:01`
 - `00-00-02-AB-CD-EF`
 - `000003ABCDEF`
 - `00 00 04 12 34 56`
+- `70-2A:54` (mixed formats)
+- `702A-54` (partial mixed)
 
 ## How to Deploy
 
 ### Using Docker Compose
-
 ```yml
 services:
   api:
@@ -34,7 +32,6 @@ services:
 ```
 
 ### Using Docker
-
 ```bash
 # Pull and run
 docker run -p 5000:8000 git.shihaam.dev/shihaam/macvendors
@@ -44,7 +41,6 @@ docker run -p 5000:8000 -v $(pwd)/mac_list.txt:/app/mac_list.txt git.shihaam.dev
 ```
 
 ### Local Development
-
 ```bash
 # Install dependencies
 pip install fastapi uvicorn httpx
@@ -56,13 +52,11 @@ uvicorn macvendorapi:app --host 0.0.0.0 --port 8000
 ## API Usage
 
 ### Endpoint
-
 ```
 GET /lookup/{mac_address}
 ```
 
 ### Examples
-
 ```bash
 # Basic lookup
 curl http://localhost:5000/lookup/70-22-FE
@@ -73,51 +67,60 @@ curl http://localhost:5000/lookup/70:22:FE
 curl http://localhost:5000/lookup/70-22-FE-12-34-56
 ```
 
-### Expected Response
+## Response Format
 
+### Success Response (HTTP 200)
+When a vendor is found:
 ```json
 {
   "mac_address": "70-22-FE",
-  "vendor": "Apple, Inc."
+  "vendor": "Apple, Inc.",
+  "detail": null
 }
 ```
 
-### Error Responses
-
-**Invalid MAC address:**
+### Not Found Response (HTTP 404)
+When MAC address is valid but vendor is not found:
 ```json
 {
+  "mac_address": "70-22-54",
+  "vendor": null,
+  "detail": "Vendor not found"
+}
+```
+
+### Error Response (HTTP 400)
+When MAC address format is invalid:
+```json
+{
+  "mac_address": "70-22-HI",
+  "vendor": null,
   "detail": "Invalid MAC address format"
 }
 ```
 
-**Unknown vendor:**
-```json
-{
-  "mac_address": "FF-FF-FF",
-  "vendor": "Unknown"
-}
-```
+## HTTP Status Codes
+- **200 OK**: Valid MAC address with vendor found
+- **400 Bad Request**: Invalid MAC address format
+- **404 Not Found**: Valid MAC address but vendor not found
 
 ## Local MAC Vendor File
-
 To improve performance, you can provide a local `mac_list.txt` file in the same format as the [IEEE OUI database](https://gist.githubusercontent.com/aallan/b4bb86db86079509e6159810ae9bd3e4/raw/846ae1b646ab0f4d646af9115e47365f4118e5f6/mac-vendor.txt):
 
 ```
-000000	Officially Xerox
-000001	SuperLAN-2U
-000002	BBN (was internal usage only, no longer used)
+000000 Officially Xerox
+000001 SuperLAN-2U
+000002 BBN (was internal usage only, no longer used)
+000003 XEROX CORPORATION
 ```
 
 ## Lookup Strategy
-
 1. **Local File**: Checks `mac_list.txt` first (fastest, no network calls)
 2. **GitHub Database**: Falls back to the official IEEE OUI database
 3. **External API**: Uses macvendors.com API as final fallback
-4. **Unknown**: Returns "Unknown" if no matches found
+4. **Not Found**: Returns vendor not found if no matches are found
 
 ## Building from Source
-
 ```bash
 # Clone repository
 git clone <repository-url>
@@ -131,7 +134,6 @@ docker run -p 8000:8000 mac-vendor-api
 ```
 
 ## Health Check
-
 ```bash
 curl http://localhost:5000/
 ```