Skip to main content

​
Endpoint

POST /articles
This endpoint requires authentication with a valid JWT token AND Admin role.

​
Description

Creates a new article in the database with optional image uploads. This endpoint is restricted to administrators only. The endpoint:
  • Validates all input data according to business rules
  • Creates the article record in a database transaction
  • Uploads and associates images if provided
  • Returns the created article with all relationships

​
Authentication

​
Authorization
string
required
Bearer token for authentication. Format: Bearer YOUR_JWT_TOKEN
User must have the Admin role. Regular users will receive a 403 Forbidden response.

​
Headers

​
Content-Type
string
required
Must be multipart/form-data when uploading images, or application/json for data only
​
Accept-Language
string
default:"en"
Language preference for response messages. Supported values: en, es
​
Accept
string
default:"application/json"
Response content type

​
Request Body Parameters

​
name
string
required
Name of the articleValidation Rules:
  • Required
  • Must be a string
  • Minimum 3 characters
​
description
string
required
Detailed description of the articleValidation Rules:
  • Required
  • Must be a string
  • Minimum 10 characters
  • Maximum 255 characters
​
price
number
required
Price of the articleValidation Rules:
  • Required
  • Must be numeric
  • Minimum value: 0
​
category_id
integer
required
ID of the category this article belongs toValidation Rules:
  • Required
  • Must exist in the categories table
​
subcategory_id
integer
required
ID of the subcategory this article belongs toValidation Rules:
  • Required
  • Must exist in the subcategories table
​
images
array
Array of image files to uploadValidation Rules:
  • Optional (nullable)
  • Must be an array if provided
  • Each image must meet the following criteria:
    • Must be a valid image file
    • Allowed formats: jpeg, png, jpg
    • Maximum size: 2048 KB (2 MB) per image

​
Response

​
Success Response (201 Created)

​
success
boolean
required
Always true for successful requests
​
message
string
required
Success message indicating the article was created
​
data
object
required

​
Example Request

curl -X POST https://api.example.com/articles \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json" \
  -H "Accept-Language: en" \
  -F "name=Gaming Laptop RTX 4070" \
  -F "description=High-performance gaming laptop with RTX 4070 graphics card, 16GB RAM, and 1TB SSD" \
  -F "price=1499.99" \
  -F "category_id=2" \
  -F "subcategory_id=5" \
  -F "images[]=@/path/to/laptop-front.jpg" \
  -F "images[]=@/path/to/laptop-side.jpg"

​
Example Response

​
Success (201 Created)

{
  "success": true,
  "message": "Article created successfully",
  "data": {
    "article": {
      "id": 1,
      "category_id": 2,
      "subcategory_id": 5,
      "name": "Gaming Laptop RTX 4070",
      "description": "High-performance gaming laptop with RTX 4070 graphics card, 16GB RAM, and 1TB SSD",
      "price": 1499.99,
      "images": [
        {
          "id": 1,
          "path": "articles/article_image_1_1709912345.jpg",
          "imageable_type": "App\\Models\\Article",
          "imageable_id": 1
        },
        {
          "id": 2,
          "path": "articles/article_image_1_1709912346.jpg",
          "imageable_type": "App\\Models\\Article",
          "imageable_id": 1
        }
      ]
    }
  }
}

​
Error Responses

​
401 - Unauthorized

{
  "success": false,
  "message": "Unauthenticated",
  "errors": null
}

​
403 - Forbidden (Not Admin)

{
  "success": false,
  "message": "Forbidden. Admin role required",
  "errors": null
}

​
422 - Validation Error

{
  "success": false,
  "message": "The given data was invalid",
  "errors": {
    "name": ["The name must be at least 3 characters."],
    "description": ["The description must be at least 10 characters."],
    "price": ["The price must be at least 0."],
    "category_id": ["The selected category is invalid."],
    "images.0": ["The image must be a file of type: jpeg, png, jpg."]
  }
}

​
500 - Internal Server Error

{
  "success": false,
  "message": "Article creation failed",
  "errors": {
    "exception": "Database transaction failed"
  }
}

​
Implementation Notes

  • Uses database transactions to ensure atomicity (article + images created together or not at all)
  • Images are stored with the prefix article_image in the articles directory
  • Image filenames include the article ID and timestamp for uniqueness
  • Maximum of 2MB per image file
  • If transaction fails, all changes (including uploaded images) are rolled back
  • Uses the HandleImageUploads trait for consistent image management
Source Code Reference: ArticleController::store() at /home/daytona/workspace/source/app/Http/Controllers/ArticleController.php:82Validation Rules: CreateArticleRequest at /home/daytona/workspace/source/app/Http/Requests/ArticleRequest/CreateArticleRequest.php:24

Build docs developers (and LLMs) love

Get started for freeTalk to us