API v3 Basics

This document provides an overview of the basic concepts and features of the API v3.

In This Document

• In This Document
• Getting Started
• URL Structure
  • Examples
• Response Format
• Core Concepts
  • Transformers
  • Repositories
• Filtering and Searching
  • Common Query Parameters
  • Example Queries
• Rate Limiting
• Error Handling

Getting Started

info

API version V3 is based on a different approach compared to V1, with new concepts designed for better management of web services. This document introduces these concepts and provides guidance on how to develop with them.

In this version, two key concepts are used: Transformers and Repositories. These components form the foundation of the API v3 architecture.

• Transformers
• Repositories

URL Structure

The API v3 follows a consistent URL structure pattern:

https://api.example.com/api/{audience}/{version}/{module}/{resource}/{id?}

Where:

• audience: Indicates the target audience (client or admin)
• version: API version (v3)
• module: The module name (e.g., cms, user, system)
• resource: The specific resource (e.g., post, category, user)
• id: Optional resource identifier for specific resource operations

Examples

Client

Client Endpoints

# List all posts
GET https://api.example.com/api/client/v3/cms/post

# Get a specific post
GET https://api.example.com/api/client/v3/cms/post/123

Admin

Admin Endpoints

# List all posts
GET https://api.example.com/api/admin/v3/cms/post

# Create a new post
POST https://api.example.com/api/admin/v3/cms/post

Response Format

All API responses follow a consistent JSON format:

Success Response

Success Response

{
  "status": true,
  "result": {
    // Response data
  },
  "meta": {
    // Metadata, pagination, etc.
  }
}

Error Response

Error Response

{
  "status": false,
  "error": {
    "code": "error_code",
    "message": "Error message"
  }
}

Core Concepts

Transformers

Transformers are an alternative to Laravel's Resources but with enhanced features. They handle the presentation layer of your API, determining how data is formatted before being sent as a response.

The API v3 uses the thephpleague/fractal package to implement transformers, providing a powerful way to format and structure API responses.

Key Features:

• Consistent response formatting
• Inclusion of related resources
• Data serialization
• Custom data presentation

Resources:

• GitHub: https://github.com/thephpleague/fractal
• Documentation: http://fractal.thephpleague.com/

tip

For detailed information on implementing transformers, see the Transformers documentation.

Repositories

Repositories encapsulate database operations, providing a clean API for data access. They abstract the underlying Eloquent ORM, promoting code organization and maintenance.

The API v3 uses the andersao/l5-repository package to implement the repository pattern, offering convenient tools for CRUD operations and query customization.

/app/Repositories/PostRepository.php

class PostRepository extends BaseRepository
{
    public function model()
    {
        return Post::class;
    }
    
    public function getPublished()
    {
        return $this->findWhere(['status' => 'published']);
    }
}

Key Benefits:

• Separation of concerns
• Code reusability
• Standardized data access
• Enhanced testability
• Simplified query logic

Resources:

• GitHub: https://github.com/andersao/l5-repository

tip

For detailed information on implementing repositories, see the Repositories documentation.

Filtering and Searching

The API v3 leverages the repository pattern to implement powerful filtering, searching, and pagination features. This provides a consistent way to query data across all endpoints.

Common Query Parameters

Parameter	Type	Description	Example
search	string	Search terms with format field:value	search=title:welcome
searchFields	string	Fields to search in	searchFields=title;content
searchJoin	string	How to join multiple search terms (and or or)	searchJoin=and
filter	array	Filter by specific field values	filter[]=status:published
orderBy	string	Field to order results by	orderBy=created_at
sortedBy	string	Direction to order results (asc or desc)	sortedBy=desc
includes	string	Related entities to include in the response	includes=author,category,tags
excludes	string	Fields to exclude from the response	excludes=content
with	array	Relationships to include	with[]=author
withCount	array	Count of related entities	withCount[]=comments
skip	integer	Number of records to skip	skip=10
limit	integer	Maximum number of records to return	limit=25
page	integer	Page number for pagination	page=2
per_page	integer	Number of items per page	per_page=20

Example Queries

Search

Search Query

# Search for posts with "API" in the title
GET /api/client/v3/cms/post?search=API&searchFields=title

Filter

Filter Query

# Get published posts ordered by creation date
GET /api/client/v3/cms/post?filter[]=status:published&orderBy=created_at&sortedBy=desc

Include Relations

Include Relations

# Get posts with author and category information
GET /api/client/v3/cms/post?includes=author,category

Pagination

Pagination

# Paginate results
GET /api/client/v3/cms/post?page=2&per_page=10

Rate Limiting

warning

API requests are subject to rate limiting to ensure fair usage and system stability.

Rate limit information is included in the response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1625097600

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request:

Status Code	Description
200	OK - The request was successful
400	Bad Request - The request was invalid
401	Unauthorized - Authentication failed
403	Forbidden - The user does not have permission
404	Not Found - The resource was not found
422	Unprocessable Entity - Validation errors
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error

Error responses include detailed information about the error:

Validation Error Example

{
  "status": false,
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": {
      "title": ["The title field is required."]
    }
  }
}