Apis

Product & Subscription Platform - API Specification Table

Base Configuration

Property	Value
Base URL	https://api.yourplatform.com/v1
Authentication	JWT Bearer Token + OAuth2
Content-Type	application/json
Rate Limiting	1000 requests/hour per user

---

Complete API Endpoints Table

Category	Method	Endpoint	Auth Level	Description	Request Body	Response
AUTHENTICATION & OAUTH2
OAuth2	POST	/auth/oauth/google	Public	Google OAuth2 login	{"code": "auth_code", "redirect_uri": "callback_url"}	JWT + User data
OAuth2	POST	/auth/oauth/github	Public	GitHub OAuth2 login	{"code": "auth_code", "redirect_uri": "callback_url"}	JWT + User data
Auth	POST	/auth/register	Public	User registration	{"email", "password", "first_name", "last_name", "phone"}	JWT + User data
Auth	POST	/auth/login	Public	User login	{"email", "password"}	JWT + User data
Auth	POST	/auth/logout	User	Logout user	None	Success message
Auth	POST	/auth/refresh	Public	Refresh JWT token	{"refresh_token"}	New JWT token
Auth	POST	/auth/forgot-password	Public	Request password reset	{"email"}	Success message
Auth	POST	/auth/reset-password	Public	Reset password	{"token", "password"}	Success message
USER MANAGEMENT
Profile	GET	/users/profile	User	Get current user profile	None	User object
Profile	PUT	/users/profile	User	Update current user	{"first_name", "last_name", "phone"}	Updated user
Profile	DELETE	/users/profile	User	Delete current user	None	Success message
Admin	GET	/users	Staff	List all users (paginated)	Query: ?page=1&limit=20&user_type=customer	User list + pagination
Admin	GET	/users/{user_id}	Staff	Get specific user	None	User object
Admin	PUT	/users/{user_id}	Staff	Update user	User fields	Updated user
Admin	DELETE	/users/{user_id}	Admin	Deactivate user	None	Success message
Admin	POST	/users/{user_id}/activate	Admin	Activate user	None	Success message
ROLE & PERMISSION MANAGEMENT
Roles	GET	/roles	Admin	List all roles	None	Role list
Roles	POST	/roles	Admin	Create new role	{"role_name", "description", "permissions"}	Created role
Roles	GET	/roles/{role_id}	Admin	Get role details	None	Role object
Roles	PUT	/roles/{role_id}	Admin	Update role	Role fields	Updated role
Roles	DELETE	/roles/{role_id}	Admin	Delete role	None	Success message
User Roles	GET	/users/{user_id}/roles	Staff	Get user’s roles	None	Role list
User Roles	POST	/users/{user_id}/roles	Admin	Assign role to user	{"role_id"}	Success message
User Roles	DELETE	/users/{user_id}/roles/{role_id}	Admin	Remove role from user	None	Success message
PRODUCT MANAGEMENT
Products	GET	/products	Public	List products	Query: ?page=1&product_type=physical&search=laptop	Product list + pagination
Products	POST	/products	Staff	Create product	{"name", "description", "price", "product_type", "sku"}	Created product
Products	GET	/products/{product_id}	Public	Get product details	None	Product object
Products	PUT	/products/{product_id}	Staff	Update product	Product fields	Updated product
Products	DELETE	/products/{product_id}	Admin	Delete product	None	Success message
Search	GET	/products/search	Public	Search products	Query: ?q=search_term&category=electronics	Product list
Featured	GET	/products/featured	Public	Get featured products	None	Product list
Popular	GET	/products/popular	Public	Get popular products	None	Product list
INVENTORY MANAGEMENT
Inventory	GET	/inventory	Staff	List all inventory	Query: ?low_stock=true	Inventory list
Inventory	GET	/inventory/{product_id}	Staff	Get product inventory	None	Inventory object
Inventory	PUT	/inventory/{product_id}	Staff	Update stock levels	{"stock_quantity", "reserved_quantity", "reorder_level"}	Updated inventory
Adjust	POST	/inventory/{product_id}/adjust	Staff	Adjust stock with reason	{"adjustment": -5, "reason": "damaged"}	Success message
SUBSCRIPTION MANAGEMENT
Plans	GET	/subscription-plans	Public	List all plans	Query: ?product_id=5&is_active=true	Plan list
Plans	POST	/subscription-plans	Staff	Create plan	{"product_id", "plan_name", "price", "billing_cycle"}	Created plan
Plans	GET	/subscription-plans/{plan_id}	Public	Get plan details	None	Plan object
Plans	PUT	/subscription-plans/{plan_id}	Staff	Update plan	Plan fields	Updated plan
Plans	DELETE	/subscription-plans/{plan_id}	Admin	Delete plan	None	Success message
Subscriptions	GET	/subscriptions	User	Get user’s subscriptions	None	Subscription list
Subscriptions	POST	/subscriptions	User	Create new subscription	{"plan_id"}	Created subscription
Subscriptions	GET	/subscriptions/{subscription_id}	User	Get subscription details	None	Subscription object
Subscriptions	PUT	/subscriptions/{subscription_id}	User	Update subscription	{"auto_renew": true}	Updated subscription
Subscriptions	DELETE	/subscriptions/{subscription_id}	User	Cancel subscription	None	Success message
Renew	POST	/subscriptions/{subscription_id}/renew	User	Renew subscription	None	Success message
ORDER MANAGEMENT
Orders	GET	/orders	User	Get user’s orders	Query: ?status=completed&page=1	Order list + pagination
Orders	POST	/orders	User	Create new order	{"items": [{"product_id", "quantity"}], "coupon_code"}	Created order
Orders	GET	/orders/{order_id}	User	Get order details	None	Order object
Orders	PUT	/orders/{order_id}	Staff	Update order status	{"status": "shipped"}	Updated order
Orders	DELETE	/orders/{order_id}	User	Cancel order	None	Success message
Admin Orders	GET	/admin/orders	Staff	List all orders	Query: ?status=pending&date_from=2024-01-01	Order list + pagination
Status	PUT	/admin/orders/{order_id}/status	Staff	Update order status	{"status": "shipped", "tracking_number": "123"}	Success message
Ship	POST	/admin/orders/{order_id}/ship	Staff	Mark as shipped	{"tracking_number": "123", "carrier": "UPS"}	Success message
Deliver	POST	/admin/orders/{order_id}/deliver	Staff	Mark as delivered	None	Success message
SHOPPING CART
Cart	GET	/cart	User	Get user’s cart	None	Cart object with items
Add Item	POST	/cart/items	User	Add item to cart	{"product_id": 1, "quantity": 2}	Updated cart
Update Item	PUT	/cart/items/{item_id}	User	Update cart item	{"quantity": 3}	Updated cart
Remove Item	DELETE	/cart/items/{item_id}	User	Remove from cart	None	Updated cart
Clear Cart	DELETE	/cart	User	Clear entire cart	None	Success message
Checkout	POST	/cart/checkout	User	Convert cart to order	{"shipping_address", "payment_method"}	Created order
COUPON MANAGEMENT
User Coupons	GET	/coupons	User	List user’s available coupons	None	Coupon list
Validate	POST	/coupons/validate	User	Validate coupon code	{"code": "SAVE10", "order_total": 100}	Validation result
Apply	POST	/coupons/apply	User	Apply coupon to order	{"code": "SAVE10", "order_id": 123}	Applied discount
Admin Coupons	GET	/admin/coupons	Staff	List all coupons	Query: ?is_active=true&expiring_soon=true	Coupon list
Create	POST	/admin/coupons	Staff	Create coupon	{"code", "discount_type", "discount_value", "valid_from", "valid_until"}	Created coupon
Details	GET	/admin/coupons/{coupon_id}	Staff	Get coupon details	None	Coupon object
Update	PUT	/admin/coupons/{coupon_id}	Staff	Update coupon	Coupon fields	Updated coupon
Delete	DELETE	/admin/coupons/{coupon_id}	Admin	Delete coupon	None	Success message
Usage Stats	GET	/admin/coupons/{coupon_id}/usage	Staff	Get usage statistics	None	Usage analytics
PAYMENT PROCESSING
Payments	GET	/payments	User	Get user’s payments	Query: ?status=completed	Payment list
Intent	POST	/payments/intent	User	Create payment intent	{"order_id": 123, "amount": 199.99, "currency": "USD"}	Payment intent
Confirm	POST	/payments/confirm	User	Confirm payment	{"payment_intent_id", "payment_method"}	Payment result
Details	GET	/payments/{payment_id}	User	Get payment details	None	Payment object
Refund	POST	/payments/{payment_id}/refund	Staff	Request refund	{"amount": 50.00, "reason": "defective item"}	Refund result
Webhooks	POST	/webhooks/stripe	System	Stripe webhook	Stripe payload	Success
Webhooks	POST	/webhooks/paypal	System	PayPal webhook	PayPal payload	Success
INVOICE MANAGEMENT
User Invoices	GET	/invoices	User	Get user’s invoices	Query: ?status=paid	Invoice list
Details	GET	/invoices/{invoice_id}	User	Get invoice details	None	Invoice object
PDF	GET	/invoices/{invoice_id}/pdf	User	Download invoice PDF	None	PDF file
Admin Invoices	GET	/admin/invoices	Staff	List all invoices	Query: ?status=overdue&customer_id=123	Invoice list
Create	POST	/admin/invoices	Staff	Create invoice	{"user_id", "order_id", "amount", "due_date"}	Created invoice
Update	PUT	/admin/invoices/{invoice_id}	Staff	Update invoice	Invoice fields	Updated invoice
Send	POST	/admin/invoices/{invoice_id}/send	Staff	Send invoice to customer	{"method": "email"}	Success message
NOTIFICATIONS
User Notifications	GET	/notifications	User	Get user’s notifications	Query: ?unread=true	Notification list
Mark Read	PUT	/notifications/{notification_id}/read	User	Mark as read	None	Success message
Delete	DELETE	/notifications/{notification_id}	User	Delete notification	None	Success message
Mark All Read	POST	/notifications/mark-all-read	User	Mark all as read	None	Success message
Admin Send	POST	/admin/notifications/send	Staff	Send notification to users	{"user_ids": [1,2,3], "title", "message", "type"}	Success message
Templates	GET	/admin/notifications/templates	Staff	Get notification templates	None	Template list
Broadcast	POST	/admin/notifications/broadcast	Admin	Broadcast to all users	{"title", "message", "type", "user_filter"}	Success message
ANALYTICS & REPORTING
User Dashboard	GET	/analytics/dashboard	User	User dashboard data	None	Dashboard metrics
Order Analytics	GET	/analytics/orders	User	Order history analytics	Query: ?period=30d	Order analytics
Subscription Analytics	GET	/analytics/subscriptions	User	Subscription analytics	Query: ?period=12m	Subscription metrics
Admin Overview	GET	/admin/analytics/overview	Admin	Platform overview	Query: ?period=30d&group_by=day	Overview metrics
Sales Analytics	GET	/admin/analytics/sales	Admin	Sales analytics	Query: ?start_date=2024-01-01&end_date=2024-01-31	Sales metrics
User Analytics	GET	/admin/analytics/users	Admin	User analytics	Query: ?segment=new_users&period=7d	User metrics
Product Analytics	GET	/admin/analytics/products	Admin	Product performance	Query: ?top_products=10&period=30d	Product metrics
Subscription Metrics	GET	/admin/analytics/subscriptions	Admin	Subscription metrics	Query: ?churn_rate=true&period=12m	Subscription analytics
AUDIT & LOGGING
Audit Logs	GET	/admin/audit-logs	Admin	Get audit logs	Query: ?action=update&table_name=products&user_id=123	Audit log list
User Actions	GET	/admin/audit-logs/user/{user_id}	Admin	Get user’s actions	Query: ?start_date=2024-01-01&action=delete	User audit logs
Table Changes	GET	/admin/audit-logs/table/{table}	Admin	Get table changes	Query: ?record_id=123&period=7d	Table audit logs
SYSTEM & HEALTH
Health	GET	/health	Public	Basic health check	None	System status
Detailed Health	GET	/health/detailed	Admin	Detailed system status	None	Detailed system info
Version	GET	/version	Public	API version info	None	Version details
System Stats	GET	/admin/system/stats	Admin	System statistics	None	System metrics
Maintenance On	POST	/admin/system/maintenance	Admin	Enable maintenance mode	{"message": "Scheduled maintenance"}	Success message
Maintenance Off	DELETE	/admin/system/maintenance	Admin	Disable maintenance mode	None	Success message

---

Authorization Levels Table

Level	Description	Endpoints Access	Rate Limit
Public	No authentication required	Health, Auth, Product browsing	100 req/hour
User	Authenticated users	Profile, Orders, Cart, Subscriptions	1000 req/hour
Staff	Operations staff role	Product/Inventory management, Order admin	5000 req/hour
Admin	Administrator role	User management, System admin, Analytics	10000 req/hour
System	Internal system calls	Webhooks, Background processes	Unlimited

---

OAuth2 Providers Table

Provider	Endpoint	Scopes Required	Redirect URI Format
Google	/auth/oauth/google	openid email profile	https://yourapp.com/callback/google
GitHub	/auth/oauth/github	user:email	https://yourapp.com/callback/github

---

Common Query Parameters Table

Category	Parameters	Description	Example
Pagination	page, limit	Page number and items per page	?page=2&limit=20
Filtering	status, type, is_active	Filter by field values	?status=active&type=physical
Search	search, q	Text search in relevant fields	?search=laptop&q=gaming
Date Range	start_date, end_date, period	Date filtering	?period=30d&start_date=2024-01-01
Sorting	sort_by, order	Sort results	?sort_by=created_at&order=desc
User Filtering	user_id, user_type	Filter by user	?user_type=customer&user_id=123

---

Response Status Codes Table

Code	Status	Description	Used For
200	OK	Success	GET, PUT requests
201	Created	Resource created	POST requests
204	No Content	Success, no response body	DELETE requests
400	Bad Request	Invalid request data	Validation errors
401	Unauthorized	Authentication required	Missing/invalid token
403	Forbidden	Insufficient permissions	Role/permission denied
404	Not Found	Resource not found	Invalid ID/endpoint
409	Conflict	Resource conflict	Duplicate entries
422	Unprocessable Entity	Validation failed	Business logic errors
429	Too Many Requests	Rate limit exceeded	Rate limiting
500	Internal Server Error	Server error	System errors

---

Environment Variables Table

Variable	Required	Description	Example
GOOGLE_CLIENT_ID	Yes	Google OAuth2 client ID	123456789-abc...googleusercontent.com
GOOGLE_CLIENT_SECRET	Yes	Google OAuth2 client secret	GOCSPX-abc123...
GITHUB_CLIENT_ID	Yes	GitHub OAuth2 client ID	Iv1.abc123...
GITHUB_CLIENT_SECRET	Yes	GitHub OAuth2 client secret	abc123def456...
JWT_SECRET	Yes	JWT signing secret	super-secure-secret-key
JWT_EXPIRES_IN	No	JWT expiration time	1h (default)
REFRESH_TOKEN_EXPIRES_IN	No	Refresh token expiration	7d (default)
DATABASE_URL	Yes	Database connection string	postgresql://user:pass@host:5432/db
REDIS_URL	No	Redis connection for caching	redis://localhost:6379
STRIPE_SECRET_KEY	Yes	Stripe payment processing	sk_test_...
STRIPE_WEBHOOK_SECRET	Yes	Stripe webhook verification	whsec_...

This comprehensive table format makes it easy to reference any API endpoint, understand authentication requirements, and see the complete structure of your platform’s API at a glance.