README.md

---
title: API Teaching Tool
emoji: 🔌
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
---

# API Teaching Tool

A simple educational API for learning HTTP methods, request/response formats, and REST API concepts.

## Quick Start

Once deployed, visit `/docs` for interactive Swagger documentation.

## Endpoints Overview

### GET Examples
| Endpoint | Description |
|----------|-------------|
| `/hello` | Simplest GET - returns greeting |
| `/time` | Returns current server time |
| `/greet?name=X` | Query parameter example |
| `/greet/{name}` | Path parameter example |
| `/search?q=X&limit=10` | Multiple query parameters |
| `/items` | List all items |
| `/items/{id}` | Get single item |

### POST Examples
| Endpoint | Description |
|----------|-------------|
| `/items` | Create new item (JSON body) |
| `/users` | Create user (JSON body) |
| `/echo` | Echo back any JSON you send |
| `/echo/text` | Echo back raw text |

### PUT/PATCH/DELETE
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/items/{id}` | PUT | Replace entire item |
| `/items/{id}` | PATCH | Partial update |
| `/items/{id}` | DELETE | Delete item |

### Response Formats
| Endpoint | Format |
|----------|--------|
| `/format/json` | JSON (default) |
| `/format/text` | Plain text |
| `/format/html` | HTML page |
| `/format/xml` | XML document |

### Educational
| Endpoint | Description |
|----------|-------------|
| `/headers` | Shows all request headers |
| `/headers/custom` | Returns custom headers |
| `/status/{code}` | Returns specified HTTP status |
| `/method` | Accepts any method, shows what was used |
| `/ip` | Shows client IP address |
| `/params/types` | Demonstrates parameter types |

## Example Usage

### Using curl

```bash
# Simple GET
curl https://nipun-api-testing.hf.space/hello

# GET with query parameter
curl "https://nipun-api-testing.hf.space/greet?name=Alice"

# POST with JSON body
curl -X POST https://nipun-api-testing.hf.space/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Book", "price": 15.99, "quantity": 10}'

# PUT to update
curl -X PUT https://nipun-api-testing.hf.space/items/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Apple", "price": 2.00, "quantity": 50}'

# DELETE
curl -X DELETE https://nipun-api-testing.hf.space/items/1

# Get different formats
curl https://nipun-api-testing.hf.space/format/xml
curl https://nipun-api-testing.hf.space/format/html

# Test status codes
curl -i https://nipun-api-testing.hf.space/status/404
curl -i https://nipun-api-testing.hf.space/status/201
```

### Using Python requests

```python
import requests

BASE = "https://nipun-api-testing.hf.space"

# GET request
response = requests.get(f"{BASE}/hello")
print(response.json())

# GET with parameters
response = requests.get(f"{BASE}/greet", params={"name": "Alice"})
print(response.json())

# POST with JSON
data = {"name": "Laptop", "price": 999.99, "quantity": 5}
response = requests.post(f"{BASE}/items", json=data)
print(response.status_code)  # 201
print(response.json())

# Check headers
response = requests.get(f"{BASE}/headers")
print(response.json())
```

## Local Development

```bash
pip install -r requirements.txt
python app.py
# Visit http://localhost:7860/docs
```

## License

MIT