309556c1a0
- Remove manual API docs (mkdocstrings generates automatically) - Remove internal docs (ARCHITECTURE, GITEA_PAGES, RELEASE, SEMANTIC_RELEASE) - Add usage.md with examples - Simplify index.md - Update mkdocs.yml (minimal config) - Remove api_reference.md duplicate
133 lines
2.4 KiB
Markdown
133 lines
2.4 KiB
Markdown
# Usage Guide
|
|
|
|
## Authentication
|
|
|
|
### Login with credentials
|
|
|
|
```python
|
|
from kwork_api import KworkClient
|
|
|
|
async with await KworkClient.login("username", "password") as client:
|
|
# Your code here
|
|
pass
|
|
```
|
|
|
|
### Restore session from token
|
|
|
|
```python
|
|
from kwork_api import KworkClient
|
|
|
|
# Save token after first login
|
|
client = await KworkClient.login("username", "password")
|
|
token = client.token # Save this
|
|
|
|
# Later, restore session
|
|
client = KworkClient(token="saved_token")
|
|
user = await client.user.get_info()
|
|
```
|
|
|
|
## API Groups
|
|
|
|
### Catalog API
|
|
|
|
```python
|
|
# Get catalog list
|
|
catalog = await client.catalog.get_list(page=1, category_id=1)
|
|
|
|
# Get kwork details
|
|
kwork = await client.catalog.get_details(kwork_id=123)
|
|
```
|
|
|
|
### Projects API (Freelance)
|
|
|
|
```python
|
|
# Get projects list
|
|
projects = await client.projects.get_list(page=1)
|
|
|
|
# Get your orders
|
|
my_orders = await client.projects.get_payer_orders()
|
|
```
|
|
|
|
### User API
|
|
|
|
```python
|
|
# Get user info
|
|
user = await client.user.get_info()
|
|
|
|
# Get reviews
|
|
reviews = await client.user.get_reviews(user_id=123)
|
|
```
|
|
|
|
### Reference API
|
|
|
|
```python
|
|
# Get cities
|
|
cities = await client.reference.get_cities()
|
|
|
|
# Get countries
|
|
countries = await client.reference.get_countries()
|
|
|
|
# Get categories
|
|
categories = await client.reference.get_categories()
|
|
```
|
|
|
|
### Notifications API
|
|
|
|
```python
|
|
# Get notifications
|
|
notifications = await client.notifications.get_list()
|
|
|
|
# Get dialogs
|
|
dialogs = await client.notifications.get_dialogs()
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
```python
|
|
from kwork_api import KworkApiError, KworkAuthError
|
|
|
|
try:
|
|
catalog = await client.catalog.get_list()
|
|
except KworkAuthError as e:
|
|
print(f"Authentication failed: {e}")
|
|
except KworkApiError as e:
|
|
print(f"API error: {e.status_code} - {e.message}")
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### Rate Limiting
|
|
|
|
Kwork doesn't have official rate limits, but be respectful:
|
|
|
|
```python
|
|
import asyncio
|
|
|
|
for page in range(1, 11):
|
|
catalog = await client.catalog.get_list(page=page)
|
|
await asyncio.sleep(0.5) # 500ms delay
|
|
```
|
|
|
|
### Session Management
|
|
|
|
Always use context manager for automatic cleanup:
|
|
|
|
```python
|
|
async with await KworkClient.login("user", "pass") as client:
|
|
# Client automatically closed
|
|
pass
|
|
```
|
|
|
|
### Save Token
|
|
|
|
Save token after first login to avoid repeated authentication:
|
|
|
|
```python
|
|
# First login
|
|
client = await KworkClient.login("user", "pass")
|
|
save_token(client.token) # Save to secure storage
|
|
|
|
# Later
|
|
client = KworkClient(token=load_token())
|
|
```
|