Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
198 lines (155 loc) · 5.08 KB

API_DOCUMENTATION.md

File metadata and controls

198 lines (155 loc) · 5.08 KB

E-commerce API Documentation

Overview

This is a comprehensive e-commerce API built with Laravel, providing all the necessary endpoints for building mobile and web applications. The API includes authentication, product management, cart functionality, order processing, reviews, and more.

API Documentation

The API is fully documented using Swagger/OpenAPI 3.0 specification. You can access the interactive documentation at:

GET /api/documentation

Authentication

The API uses Laravel Sanctum for authentication. After registration or login, you'll receive a bearer token that should be included in the Authorization header for protected endpoints.

Authorization: Bearer {your-token-here}

Base URL

{your-domain}/api/ecommerce

Available Endpoints

Authentication

  • POST /register - Register a new customer
  • POST /login - Login customer
  • POST /logout - Logout customer (requires auth)
  • POST /forgot-password - Request password reset
  • POST /reset-password - Reset password

Products

  • GET /products - Get products with advanced filtering
  • GET /products/featured - Get featured products
  • GET /products/search - Search products with suggestions
  • GET /products/{id} - Get single product
  • GET /products/{id}/related - Get related products
  • GET /products/{id}/reviews - Get product reviews

Categories & Brands

  • GET /categories - Get all categories
  • GET /categories/{id} - Get single category
  • GET /categories/{id}/products - Get category products
  • GET /brands - Get all brands
  • GET /brands/{id} - Get single brand
  • GET /brands/{id}/products - Get brand products

Cart Management

  • POST /cart/add - Add product to cart
  • GET /cart - Get cart contents
  • GET /cart/count - Get cart item count
  • PUT /cart/{item} - Update cart item
  • DELETE /cart/{item} - Remove cart item
  • DELETE /cart/clear - Clear entire cart

Orders (Authenticated)

  • POST /orders - Create new order
  • GET /orders/{id} - Get order details
  • POST /orders/{id}/cancel - Cancel order
  • GET /orders/{id}/track - Track order

Reviews (Authenticated)

  • POST /products/{id}/reviews - Create product review
  • PUT /reviews/{id} - Update review
  • DELETE /reviews/{id} - Delete review

Customer Management (Authenticated)

  • GET /customer/profile - Get customer profile
  • PUT /customer/profile - Update customer profile
  • GET /customer/orders - Get customer orders
  • GET /customer/orders/{id} - Get specific order details

Address Management (Authenticated)

  • GET /addresses - Get customer addresses
  • POST /addresses - Create new address
  • PUT /addresses/{id} - Update address
  • DELETE /addresses/{id} - Delete address

Wishlist (Authenticated)

  • GET /wishlist - Get wishlist items
  • POST /wishlist/{product} - Add to wishlist
  • DELETE /wishlist/{product} - Remove from wishlist

Coupons

  • POST /coupon/apply - Apply coupon to cart
  • DELETE /coupon/remove - Remove applied coupon

Shipping

  • GET /shipping/methods - Get available shipping methods
  • POST /shipping/calculate - Calculate shipping cost

Payment

  • GET /payment/methods - Get available payment methods
  • POST /payment/process - Process payment (requires auth)

Request/Response Format

All requests and responses are in JSON format.

Successful Response

{
    "data": {...},
    "message": "Success message"
}

Error Response

{
    "message": "Error message",
    "errors": {
        "field": ["Validation error message"]
    }
}

Pagination Response

{
    "data": [...],
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": "..."
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "per_page": 15,
        "to": 15,
        "total": 75
    }
}

Product Filtering

The products endpoint supports advanced filtering:

  • category - Filter by category ID
  • brand - Filter by brand ID
  • search - Search in name, description, SKU
  • min_price - Minimum price filter
  • max_price - Maximum price filter
  • in_stock - Filter only in-stock products
  • sort_by - Sort by: price_low_high, price_high_low, name, created_at
  • sort_order - Sort order: asc, desc
  • per_page - Items per page (default: 15)

Example:

GET /api/ecommerce/products?category=1&min_price=10&max_price=100&sort_by=price_low_high&per_page=20

Error Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 409 - Conflict
  • 422 - Validation Error
  • 500 - Internal Server Error

Rate Limiting

The API implements rate limiting to prevent abuse. Default limits:

  • 60 requests per minute for authenticated users
  • 30 requests per minute for guest users

Testing

You can test the API using the provided test suite:

php artisan test

Support

For support and questions, please contact:

License

This API is open-sourced software licensed under the MIT license.