ALwrity Version 0.5.0 (Fastapi + React )
This commit is contained in:
ajaysi
449
Getting Started/docs/architecture/api_design.rst
Normal file
449
Getting Started/docs/architecture/api_design.rst
Normal file
@@ -0,0 +1,449 @@
|
||||
API Design
|
||||
=========
|
||||
|
||||
This document outlines the API design principles and specifications for the AI-Writer platform.
|
||||
|
||||
API Design Principles
|
||||
-------------------
|
||||
|
||||
The AI-Writer API follows these core design principles:
|
||||
|
||||
1. **RESTful Architecture**
|
||||
|
||||
* Resource-oriented design
|
||||
* Standard HTTP methods (GET, POST, PUT, DELETE)
|
||||
* Consistent URL structure
|
||||
* Stateless interactions
|
||||
|
||||
2. **Consistent Response Format**
|
||||
|
||||
* JSON as the primary data format
|
||||
* Standard error response structure
|
||||
* Pagination for list endpoints
|
||||
* Hypermedia links where appropriate
|
||||
|
||||
3. **Versioning**
|
||||
|
||||
* API versioning in URL path (e.g., `/api/v1/`)
|
||||
* Backward compatibility within major versions
|
||||
* Deprecation notices before removing features
|
||||
|
||||
4. **Security**
|
||||
|
||||
* Authentication via API keys or OAuth 2.0
|
||||
* Rate limiting to prevent abuse
|
||||
* Input validation to prevent injection attacks
|
||||
* HTTPS for all communications
|
||||
|
||||
5. **Documentation**
|
||||
|
||||
* OpenAPI/Swagger specification
|
||||
* Interactive documentation
|
||||
* Code examples for common operations
|
||||
* Changelog for API updates
|
||||
|
||||
API Endpoints
|
||||
-----------
|
||||
|
||||
Content Management
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Create content
|
||||
POST /api/v1/content
|
||||
|
||||
# Get content by ID
|
||||
GET /api/v1/content/{content_id}
|
||||
|
||||
# Update content
|
||||
PUT /api/v1/content/{content_id}
|
||||
|
||||
# Delete content
|
||||
DELETE /api/v1/content/{content_id}
|
||||
|
||||
# List content with filtering
|
||||
GET /api/v1/content?type={type}&limit={limit}&offset={offset}
|
||||
|
||||
# Get content versions
|
||||
GET /api/v1/content/{content_id}/versions
|
||||
|
||||
# Revert to specific version
|
||||
POST /api/v1/content/{content_id}/revert/{version_id}
|
||||
|
||||
AI Generation
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Generate content from keywords
|
||||
POST /api/v1/generate/content
|
||||
|
||||
# Generate blog post
|
||||
POST /api/v1/generate/blog
|
||||
|
||||
# Generate social media post
|
||||
POST /api/v1/generate/social
|
||||
|
||||
# Generate email
|
||||
POST /api/v1/generate/email
|
||||
|
||||
# Generate outline
|
||||
POST /api/v1/generate/outline
|
||||
|
||||
# Generate image for content
|
||||
POST /api/v1/generate/image
|
||||
|
||||
Web Research
|
||||
~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Perform web research
|
||||
POST /api/v1/research
|
||||
|
||||
# Get research results
|
||||
GET /api/v1/research/{research_id}
|
||||
|
||||
# Search previous research
|
||||
GET /api/v1/research/search?query={query}
|
||||
|
||||
SEO Tools
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Analyze content for SEO
|
||||
POST /api/v1/seo/analyze
|
||||
|
||||
# Generate meta description
|
||||
POST /api/v1/seo/meta-description
|
||||
|
||||
# Generate SEO-friendly title
|
||||
POST /api/v1/seo/title
|
||||
|
||||
# Generate structured data
|
||||
POST /api/v1/seo/structured-data
|
||||
|
||||
# Generate alt text for images
|
||||
POST /api/v1/seo/alt-text
|
||||
|
||||
User Management
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Create user
|
||||
POST /api/v1/users
|
||||
|
||||
# Get user profile
|
||||
GET /api/v1/users/{user_id}
|
||||
|
||||
# Update user profile
|
||||
PUT /api/v1/users/{user_id}
|
||||
|
||||
# Delete user
|
||||
DELETE /api/v1/users/{user_id}
|
||||
|
||||
# Get user settings
|
||||
GET /api/v1/users/{user_id}/settings
|
||||
|
||||
# Update user settings
|
||||
PUT /api/v1/users/{user_id}/settings
|
||||
|
||||
API Key Management
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Create API key
|
||||
POST /api/v1/api-keys
|
||||
|
||||
# List API keys
|
||||
GET /api/v1/api-keys
|
||||
|
||||
# Revoke API key
|
||||
DELETE /api/v1/api-keys/{key_id}
|
||||
|
||||
Analytics
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# Get content analytics
|
||||
GET /api/v1/analytics/content/{content_id}
|
||||
|
||||
# Get user analytics
|
||||
GET /api/v1/analytics/user/{user_id}
|
||||
|
||||
# Get system analytics
|
||||
GET /api/v1/analytics/system
|
||||
|
||||
Request and Response Examples
|
||||
---------------------------
|
||||
|
||||
Create Content
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Request:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
POST /api/v1/content
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {api_key}
|
||||
|
||||
{
|
||||
"title": "How to Improve SEO with AI",
|
||||
"content_type": "blog",
|
||||
"content": "# How to Improve SEO with AI\n\nIn this article, we'll explore...",
|
||||
"metadata": {
|
||||
"keywords": ["SEO", "AI", "content marketing"],
|
||||
"category": "digital marketing",
|
||||
"language": "en"
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"id": "c123e4567-e89b-12d3-a456-426614174000",
|
||||
"title": "How to Improve SEO with AI",
|
||||
"content_type": "blog",
|
||||
"content": "# How to Improve SEO with AI\n\nIn this article, we'll explore...",
|
||||
"metadata": {
|
||||
"keywords": ["SEO", "AI", "content marketing"],
|
||||
"category": "digital marketing",
|
||||
"language": "en"
|
||||
},
|
||||
"created_at": "2023-01-01T12:00:00Z",
|
||||
"updated_at": "2023-01-01T12:00:00Z",
|
||||
"user_id": "u123e4567-e89b-12d3-a456-426614174000",
|
||||
"links": {
|
||||
"self": "/api/v1/content/c123e4567-e89b-12d3-a456-426614174000",
|
||||
"versions": "/api/v1/content/c123e4567-e89b-12d3-a456-426614174000/versions",
|
||||
"analytics": "/api/v1/analytics/content/c123e4567-e89b-12d3-a456-426614174000"
|
||||
}
|
||||
}
|
||||
|
||||
Generate Blog Post
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Request:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
POST /api/v1/generate/blog
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {api_key}
|
||||
|
||||
{
|
||||
"keywords": ["artificial intelligence", "content creation"],
|
||||
"title": "The Future of Content Creation with AI",
|
||||
"tone": "informative",
|
||||
"length": "medium",
|
||||
"include_research": true,
|
||||
"target_audience": "marketers"
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"id": "g123e4567-e89b-12d3-a456-426614174000",
|
||||
"title": "The Future of Content Creation with AI",
|
||||
"content": "# The Future of Content Creation with AI\n\nArtificial intelligence is revolutionizing...",
|
||||
"metadata": {
|
||||
"keywords": ["artificial intelligence", "content creation"],
|
||||
"tone": "informative",
|
||||
"length": "medium",
|
||||
"word_count": 1250,
|
||||
"research_sources": [
|
||||
{
|
||||
"title": "AI in Content Marketing Report 2023",
|
||||
"url": "https://example.com/report",
|
||||
"accessed_at": "2023-01-01T10:30:00Z"
|
||||
}
|
||||
]
|
||||
},
|
||||
"created_at": "2023-01-01T12:05:00Z",
|
||||
"links": {
|
||||
"save": "/api/v1/content",
|
||||
"regenerate": "/api/v1/generate/blog",
|
||||
"edit": "/api/v1/generate/edit"
|
||||
}
|
||||
}
|
||||
|
||||
Error Response
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
HTTP/1.1 400 Bad Request
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"error": {
|
||||
"code": "invalid_request",
|
||||
"message": "The request was invalid",
|
||||
"details": [
|
||||
{
|
||||
"field": "keywords",
|
||||
"issue": "required",
|
||||
"description": "The keywords field is required"
|
||||
}
|
||||
]
|
||||
},
|
||||
"request_id": "req_123456",
|
||||
"documentation_url": "https://docs.alwrity.com/api/errors#invalid_request"
|
||||
}
|
||||
|
||||
API Authentication
|
||||
----------------
|
||||
|
||||
The AI-Writer API supports the following authentication methods:
|
||||
|
||||
1. **API Key Authentication**
|
||||
|
||||
* Include the API key in the Authorization header:
|
||||
`Authorization: Bearer {api_key}`
|
||||
* API keys can be generated and managed through the API or web interface
|
||||
* Different permission levels can be assigned to API keys
|
||||
|
||||
2. **OAuth 2.0 (for multi-user deployments)**
|
||||
|
||||
* Standard OAuth 2.0 flow with authorization code
|
||||
* Supports scopes for fine-grained permissions
|
||||
* Refresh token rotation for enhanced security
|
||||
|
||||
Rate Limiting
|
||||
-----------
|
||||
|
||||
To ensure fair usage and system stability, the API implements rate limiting:
|
||||
|
||||
* Rate limits are based on the user's plan
|
||||
* Limits are applied per API key
|
||||
* Rate limit information is included in response headers:
|
||||
* `X-RateLimit-Limit`: Total requests allowed in the current period
|
||||
* `X-RateLimit-Remaining`: Requests remaining in the current period
|
||||
* `X-RateLimit-Reset`: Time when the rate limit resets (Unix timestamp)
|
||||
|
||||
When a rate limit is exceeded, the API returns a 429 Too Many Requests response.
|
||||
|
||||
Pagination
|
||||
---------
|
||||
|
||||
List endpoints support pagination with the following parameters:
|
||||
|
||||
* `limit`: Number of items per page (default: 20, max: 100)
|
||||
* `offset`: Number of items to skip (for offset-based pagination)
|
||||
* `cursor`: Cursor for the next page (for cursor-based pagination)
|
||||
|
||||
Response includes pagination metadata:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"total": 45,
|
||||
"limit": 20,
|
||||
"offset": 0,
|
||||
"next_cursor": "cursor_for_next_page",
|
||||
"has_more": true
|
||||
}
|
||||
}
|
||||
|
||||
Filtering and Sorting
|
||||
-------------------
|
||||
|
||||
List endpoints support filtering and sorting:
|
||||
|
||||
* Filtering: `?field=value&another_field=another_value`
|
||||
* Range filtering: `?created_at_gte=2023-01-01&created_at_lte=2023-01-31`
|
||||
* Sorting: `?sort=field` (ascending) or `?sort=-field` (descending)
|
||||
* Multiple sort fields: `?sort=-created_at,title`
|
||||
|
||||
Versioning Strategy
|
||||
-----------------
|
||||
|
||||
The API uses a versioning strategy to ensure backward compatibility:
|
||||
|
||||
1. **Major Versions**
|
||||
|
||||
* Included in the URL path: `/api/v1/`, `/api/v2/`, etc.
|
||||
* Major versions may introduce breaking changes
|
||||
* Previous major versions are supported for at least 12 months after a new version is released
|
||||
|
||||
2. **Minor Updates**
|
||||
|
||||
* Backward-compatible changes within a major version
|
||||
* New endpoints or parameters may be added
|
||||
* Existing functionality remains unchanged
|
||||
|
||||
3. **Deprecation Process**
|
||||
|
||||
* Features to be removed are marked as deprecated
|
||||
* Deprecation notices are included in response headers
|
||||
* Deprecated features are supported for at least 6 months before removal
|
||||
|
||||
API Changelog
|
||||
-----------
|
||||
|
||||
The API changelog is maintained to track changes:
|
||||
|
||||
* **v1.0.0 (2023-01-01)**
|
||||
|
||||
* Initial release with core content management features
|
||||
* Basic AI generation capabilities
|
||||
* User management and authentication
|
||||
|
||||
* **v1.1.0 (2023-03-15)**
|
||||
|
||||
* Added SEO analysis endpoints
|
||||
* Enhanced content generation with research integration
|
||||
* Improved error handling and validation
|
||||
|
||||
* **v1.2.0 (2023-06-30)**
|
||||
|
||||
* Added analytics endpoints
|
||||
* Introduced cursor-based pagination
|
||||
* Added support for content versioning
|
||||
|
||||
Future API Roadmap
|
||||
----------------
|
||||
|
||||
Planned API enhancements:
|
||||
|
||||
1. **Content Collaboration**
|
||||
|
||||
* Endpoints for collaborative editing
|
||||
* Comment and feedback functionality
|
||||
* Role-based access control
|
||||
|
||||
2. **Advanced Analytics**
|
||||
|
||||
* Predictive performance metrics
|
||||
* Competitive analysis
|
||||
* Content optimization recommendations
|
||||
|
||||
3. **Workflow Automation**
|
||||
|
||||
* Scheduled content generation
|
||||
* Approval workflows
|
||||
* Integration with publishing platforms
|
||||
|
||||
4. **Multi-modal Content**
|
||||
|
||||
* Enhanced image generation
|
||||
* Audio content generation
|
||||
* Video script generation
|
||||
Reference in New Issue
Block a user