Introduction

Welcome to the Blog API. All responses are returned in JSON format. Authentication is handled via Laravel Sanctum Bearer tokens.

GitHub Developer

Database Seeded Accounts

After running php artisan migrate --seed, you can use these pre-defined accounts to test the API permissions and features.

Admin Access

Email: admin@example.com

Pass: password

User Access

Email: user@example.com

Pass: password

Base URL

https://blog.yuldoshew.uz/api

Standard Response Format

Used by BaseController

{
  "status": "success",
  "status_code": 200,
  "message": "Operation successful.",
  "data": { ... },
  "error_note": null
}
POST

Register User

/register

Creates a new user account and returns an access token.

Body Parameters

name* string User's full name. Max 255 chars.
email* string Must be a valid email and unique in database.
password* string Min 8 chars. Must be confirmed.
password_confirmation* string Must match the password field exactly.
201 Created 
{
  "status": "success",
  "status_code": 201,
  "message": "User registered successfully. Please verify your email.",
  "data": {
    "user": {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "user",
      "id": 1
    },
    "token": "1|AbCdEf..."
  },
  "error_note": null
}
400 Bad Request 
{
  "status": "error",
  "status_code": 400,
  "error_message": "Registration failed.",
  "error_note": "Validation error or database issue."
}
POST

Login

/login

Authenticate user and create a new API token.

Body Parameters

email* string Valid user email.
password* string User password.
200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "User logged in successfully.",
  "data": {
    "user": { "id": 1, "name": "John" },
    "token": "2|Zxy..."
  }
}
401 Unauthorized 
{
  "status": "error",
  "status_code": 401,
  "error_message": "Unauthorized.",
  "errors": {
    "email": "Invalid credentials."
  },
  "error_note": "Credentials mismatch."
}
GET

Current User

/user
AUTH REQUIRED

Retrieve the authenticated user's profile information.

200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "User profile retrieved.",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "role": "user",
    "created_at": "2024-01-01..."
  }
}
POST

Resend Verification

/email/verification-notification
AUTH REQUIRED

Sends a new email verification link to the authenticated user. If the email is already verified, it returns a 400 error.

Body Parameters

No parameters required. The user is identified via the Bearer Token.

200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "Verification link sent.",
  "data": null,
  "error_note": null
}
400 Bad Request 
{
  "status": "error",
  "status_code": 400,
  "error_message": "Already verified.",
  "error_note": "Email already verified."
}
GET

Verify Email

/email/verify/{id}/{hash}
AUTH REQUIRED

Validates the user's email address using the ID and hash provided in the verification link.

URL Parameters

id* integer The unique ID of the user.
hash* string The verification hash sent to the user's email.
200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "Email verified successfully.",
  "data": null
}
200 OK (Informational) 
{
  "status": "success",
  "status_code": 200,
  "message": "Email already verified.",
  "data": null
}
POST

Forgot Password

/forgot-password

Sends a password reset link to the user's email address if it exists in our system.

Body Parameters

email* string Registered user email address. Must be a valid email.
200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "Reset link sent to your email.",
  "data": null,
  "error_note": null
}
400 Bad Request 
{
  "status": "error",
  "status_code": 400,
  "error_message": "Failed.",
  "error_note": "Email not found or error occurred."
}
POST

Reset Password

/reset-password

Updates the user's password using the token received via email.

Body Parameters

token* string The reset token received in the email.
email* string User's email address.
password* string New password. Min 8 chars, must be confirmed.
password_confirmation* string Must match the password field.
200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "Password reset successfully.",
  "data": null
}
400 Bad Request 
{
  "status": "error",
  "status_code": 400,
  "error_message": "Reset failed.",
  "error_note": "Invalid token or email."
}
PUT

Update Password

/user/password-update
AUTH REQUIRED VERIFIED

Body Parameters

current_password* string Must match the user's current password.
password* string New password. Min 8 chars.
password_confirmation* string Must confirm new password.
200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "Password updated successfully.",
  "data": null
}
422 Unprocessable 
{
  "message": "The current password is incorrect.",
  "errors": {
    "current_password": [
       "The current password is incorrect."
    ]
  }
}
POST

Logout

/logout
AUTH REQUIRED

Revokes the current access token. User must login again to access protected resources.

200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "Logged out successfully.",
  "data": null
}
DELETE

Delete Account

/user/delete
AUTH REQUIRED DANGER

Permanently deletes the user record and all associated data/tokens. This action cannot be undone.

200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "Account deleted successfully.",
  "data": null
}
GET

Users List

/users-list
AUTH REQUIRED ADMIN ONLY

Retrieves a paginated list of all registered users.

Requires admin middleware. Standard users will receive a 403 Forbidden response.

200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "Users list retrieved.",
  "data": [
    { "id": 1, "name": "Admin", "role": "admin" },
    { "id": 2, "name": "User", "role": "user" }
  ],
  "links": { ... },
  "meta": { ... }
}
GET

List Categories

/categories
PUBLIC

Fetch all categories. This is a public endpoint used for navigation or filtering posts.

200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "Categories retrieved successfully.",
  "data": [
    { "id": 1, "name": "Tech", "slug": "tech" },
    { "id": 2, "name": "Design", "slug": "design" }
  ]
}
GET

Single Category

/categories/{id}

Retrieve detailed information about a specific category by its ID.

Path Parameters

id* integer The unique identifier of the category.
200 OK 
{
  "status": "success",
  "status_code": 200,
  "message": "Category details.",
  "data": {
    "id": 1,
    "name": "Tech",
    "slug": "tech"
  }
}
POST

Create Category

/categories
AUTH VERIFIED ADMIN

Body Parameters

name* string The name of the category. Must be unique.
201 Created
{
  "status": "success",
  "status_code": 201,
  "message": "Category created successfully.",
  "data": { "id": 3, "name": "AI" }
}
403 Forbidden
{
  "status": "error",
  "status_code": 403,
  "error_message": "Access Denied."
}
PUT

Update Category

/categories/{id}
ADMIN ONLY

Body Parameters

name* string New category name.
200 OK
{
  "status": "success",
  "status_code": 200,
  "message": "Category updated.",
  "data": { "id": 1, "name": "Updated Tech" }
}
DELETE

Delete Category

/categories/{id}
ADMIN ONLY

Permanently deletes the category.

200 OK
{
  "status": "success",
  "status_code": 200,
  "message": "Category deleted successfully.",
  "data": null
}
GET

List Posts

/posts
PUBLIC ACCESS

Returns only **published** posts with pagination. Includes user, category info, and like counts.

Query Parameters

per_page int Results per page (Default: 10).
search string Search in title or body content.
category_id int Filter posts by a specific category.
200 OK
{
  "status": "success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 1,
        "title": "Post Title",
        "likes_count": 5,
        "user": { "id": 1, "name": "Admin" },
        "category": { "id": 1, "name": "Tech" }
      }
    ]
  }
}
GET

Admin All Posts

/posts_all
ADMIN ONLY

Administrative endpoint to view all posts, including **drafts**. Supports the same filters as the public index.

200 OK
// Returns full paginated list including drafts
GET

Single Post Details

/posts/{id}
PUBLIC ACCESS

Retrieves full details of a specific post. Accessing this endpoint automatically increments the views_count field.

Path Parameters

id* integer/slug The unique ID of the post to retrieve.

Includes (Relationships)

This endpoint automatically returns the following nested objects:

  • user: The author's basic profile.
  • category: The category the post belongs to.
  • comments: All comments associated with this post.
200 OK 
{
  "status": "success",
  "message": "Post details retrieved.",
  "data": {
    "id": 1,
    "title": "Mastering Laravel APIs",
    "body": "Full post content here...",
    "views_count": 154,
    "user": { "id": 1, "name": "Admin" },
    "category": { "id": 2, "name": "Backend" },
    "comments": [...]
  }
}
404 Not Found 
{
  "status": "error",
  "message": "Post not found!"
}
POST

Create Post

/posts
ADMIN ONLY

Request Body (Multipart/Form-Data)

category_id* int Must exist in categories table.
title* string Maximum 255 characters.
body* text The main content of the post.
image file JPG, JPEG, PNG (Max: 4MB).
status string Choices: draft, published.
201 Created
{
  "status": "success",
  "status_code": 201,
  "data": {
    "id": 10,
    "title": "How to use Laravel",
    "image": "posts/filename.jpg",
    "user_id": 1
  }
}
PUT

Update Post

/posts/{id}
ADMIN ONLY

Updates post details and automatically generates a new slug if the title is changed. Replaces existing image if a new one is provided.

Pro-Tip: PHP/Laravel sometimes struggles with multipart/form-data on PUT requests. Use POST and add _method: PUT to your body fields.

200 OK
{
  "status": "success",
  "message": "Post updated successfully.",
  "data": { "slug": "new-generated-slug" }
}
DELETE

Delete Post

/posts/{id}
ADMIN ONLY

Deletes post and permanently removes the associated image file from disk.

200 OK
{
  "status": "success",
  "message": "Post deleted successfully.",
  "data": []
}
GET

List Comments

/posts/{postId}/comments
PUBLIC

Fetch all comments associated with a specific post. Usually includes user profiles for display.

Path Parameters

postId* integer The ID of the parent post.
200 OK
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "body": "Great post! Thanks for sharing.",
      "user": { "name": "John Doe" },
      "created_at": "2024-05-20..."
    }
  ]
}
POST

Post Comment

/posts/{postId}/comments
AUTH VERIFIED

Body Parameters

body* string The content of the comment.
201 Created
{
  "status": "success",
  "message": "Comment added.",
  "data": { "id": 5, "body": "Hello world" }
}
PUT

Edit Comment

/comments/{comment}
OWNER ONLY

Updates the body of an existing comment. Requires the user to be the original author.

Body Parameters

body* string Updated content.
200 OK
// Returns updated comment data
DELETE

Delete Comment

/comments/{comment}

Permanently removes the comment. Authorized for owners and administrators.

200 OK
{
  "status": "success",
  "message": "Comment deleted."
}
POST

Toggle Like

/posts/{post}/like
AUTH VERIFIED

This is a dynamic endpoint. If the user has not liked the post, it will create a "Like". If they have already liked it, the "Like" will be removed (Unlike).

Path Parameters

post* integer The unique ID of the post.
200 OK (Liked)
{
  "status": "success",
  "message": "Post liked.",
  "data": { "liked": true }
}
200 OK (Unliked)
{
  "status": "success",
  "message": "Post unliked.",
  "data": { "liked": false }
}
GET

My Favorites

/my-favorites
AUTH REQUIRED

Returns a paginated list of posts that the currently authenticated user has liked.

200 OK
{
  "status": "success",
  "data": [
    {
      "id": 12,
      "title": "A post I liked earlier",
      "created_at": "2024-06-01"
    }
  ]
}