首頁 探索 說明
登入
yusuf
/
website-be
1
0
複刻 0
Files 問題管理 0 合併請求 0 Wiki
目錄樹: d6577a9c0f
分支列表 標籤列表
website-be
/
API_DOCUMENTATION.md

API_DOCUMENTATION.md 9.0 KB
文件歷史 原始文件

API Documentation - Read-Only Endpoints

Dokumentasi API untuk frontend yang hanya dapat membaca data dari collections posts, clients, dan careers.

Base URL

Semua endpoint menggunakan base URL Payload CMS:

/api/{collection-slug}

Authentication

Endpoints ini bersifat public read-only, tidak memerlukan authentication untuk membaca data.

1. Posts API

Base Endpoint: /api/posts

Collection untuk News dan Blog posts. Menggunakan field type untuk membedakan antara "news" dan "blog".

Endpoints

GET /api/posts

Mengambil daftar posts dengan pagination dan filtering.

Query Parameters:

  • page - Nomor halaman (default: 1)
  • limit - Jumlah item per halaman (default: 10)
  • sort - Sorting field (contoh: -publishedDate untuk descending, publishedDate untuk ascending)
  • where[type][equals] - Filter berdasarkan type: "news" atau "blog"
  • where[category][equals] - Filter berdasarkan category (text)
  • where[slug][equals] - Filter berdasarkan slug (untuk single post lookup)
  • where[author][equals] - Filter berdasarkan author ID
  • where[publishedDate][greater_than] - Filter posts setelah tanggal tertentu
  • where[publishedDate][less_than] - Filter posts sebelum tanggal tertentu
  • depth - Depth untuk populate relationships (default: 0, gunakan 1-2 untuk populate author dan image)

Response Structure:

  • docs - Array of post objects
  • totalDocs - Total jumlah dokumen
  • limit - Limit per halaman
  • totalPages - Total jumlah halaman
  • page - Halaman saat ini
  • hasPrevPage - Boolean, apakah ada halaman sebelumnya
  • hasNextPage - Boolean, apakah ada halaman selanjutnya

Post Object Fields:

  • id - Unique identifier
  • type - "news" atau "blog"
  • category - Category name (string)
  • title - Post title (string)
  • slug - URL-friendly slug (string, unique)
  • image - Media object atau ID (relationship ke media)
  • excerpt - Short description/teaser (string)
  • publishedDate - Published date (ISO date string)
  • content - Rich text content (Lexical JSON structure)
  • author - Author object atau ID (relationship ke authors)
  • createdAt - Creation timestamp (ISO date string)
  • updatedAt - Last update timestamp (ISO date string)

GET /api/posts/:id

Mengambil single post berdasarkan ID.

Path Parameters:

  • id - Post ID

Query Parameters:

  • depth - Depth untuk populate relationships (recommended: 2 untuk populate author dan image secara lengkap)

Response: Single post object

2. Clients API

Base Endpoint: /api/clients

Collection untuk client/partner logos dan informasi.

Endpoints

GET /api/clients

Mengambil daftar clients dengan pagination dan filtering.

Query Parameters:

  • page - Nomor halaman (default: 1)
  • limit - Jumlah item per halaman (default: 10)
  • sort - Sorting field (contoh: name untuk ascending, -name untuk descending)
  • where[category][equals] - Filter berdasarkan category:
    • "Banking & Finance"
    • "Enterprise & Industrial"
    • "Government"
  • where[name][contains] - Search berdasarkan nama client (case-insensitive)
  • depth - Depth untuk populate logo relationship (default: 0, gunakan 1 untuk populate logo object)

Response Structure:

  • docs - Array of client objects
  • totalDocs - Total jumlah dokumen
  • limit - Limit per halaman
  • totalPages - Total jumlah halaman
  • page - Halaman saat ini
  • hasPrevPage - Boolean
  • hasNextPage - Boolean

Client Object Fields:

  • id - Unique identifier
  • name - Client name (string)
  • href - Website URL (string)
  • logo - Media object atau ID (relationship ke media)
  • category - Category (string, salah satu dari tiga opsi di atas)
  • imageHeight - Optional image height in pixels (number)
  • createdAt - Creation timestamp (ISO date string)
  • updatedAt - Last update timestamp (ISO date string)

GET /api/clients/:id

Mengambil single client berdasarkan ID.

Path Parameters:

  • id - Client ID

Query Parameters:

  • depth - Depth untuk populate logo relationship (recommended: 1)

Response: Single client object

3. Careers API

Base Endpoint: /api/careers

Collection untuk job openings dan career opportunities.

Endpoints

GET /api/careers

Mengambil daftar career positions dengan pagination dan filtering.

Query Parameters:

  • page - Nomor halaman (default: 1)
  • limit - Jumlah item per halaman (default: 10)
  • sort - Sorting field (contoh: -createdAt untuk newest first)
  • where[jobCategory][equals] - Filter berdasarkan job category:
    • "Technology & Engineering"
    • "Marketing, Sales & Communication"
    • "Finance & Accounting"
    • "Human Resources & General Affairs"
    • "Creative & Design"
    • "Operations & Customer Success"
  • where[isUrgentlyHiring][equals] - Filter hanya urgent positions (boolean: true atau false)
  • where[slug][equals] - Filter berdasarkan slug (untuk single career lookup)
  • where[title][contains] - Search berdasarkan job title (case-insensitive)
  • depth - Depth untuk populate image relationship (default: 0, gunakan 1 untuk populate image object)

Response Structure:

  • docs - Array of career objects
  • totalDocs - Total jumlah dokumen
  • limit - Limit per halaman
  • totalPages - Total jumlah halaman
  • page - Halaman saat ini
  • hasPrevPage - Boolean
  • hasNextPage - Boolean

Career Object Fields:

  • id - Unique identifier
  • title - Job title (string)
  • slug - URL-friendly slug (string, unique)
  • image - Media object atau ID (relationship ke media, optional)
  • requirements - Array of requirement objects, setiap object memiliki:
    • item - Requirement text (string)
  • mainJobDescription - Array of job description objects, setiap object memiliki:
    • item - Job description text (string)
  • isUrgentlyHiring - Boolean flag untuk urgent positions
  • jobCategory - Job category (string, salah satu dari enam opsi di atas)
  • createdAt - Creation timestamp (ISO date string)
  • updatedAt - Last update timestamp (ISO date string)

GET /api/careers/:id

Mengambil single career position berdasarkan ID.

Path Parameters:

  • id - Career ID

Query Parameters:

  • depth - Depth untuk populate image relationship (recommended: 1)

Response: Single career object

Media Relationships

Semua collections yang memiliki field upload (image/logo) akan mengembalikan relationship ke collection media.

Untuk mendapatkan informasi lengkap media (URL, dimensions, dll), gunakan parameter depth=1 atau depth=2 pada request, atau fetch langsung ke /api/media/:id.

Media Object Structure (ketika di-populate dengan depth)

  • id - Media ID
  • alt - Alt text untuk accessibility
  • filename - Nama file
  • mimeType - MIME type (contoh: image/jpeg)
  • filesize - Ukuran file dalam bytes
  • width - Lebar gambar dalam pixels
  • height - Tinggi gambar dalam pixels
  • url - Public URL untuk mengakses file
  • createdAt - Creation timestamp
  • updatedAt - Last update timestamp

Query Operators Reference

Payload CMS mendukung berbagai query operators untuk filtering:

Comparison Operators

  • equals - Exact match
  • not_equals - Not equal
  • in - Value dalam array (contoh: where[type][in]=news,blog)
  • not_in - Value tidak dalam array
  • contains - Contains substring (case-insensitive untuk text)
  • like - Like search (semua kata harus ada)
  • exists - Field exists (boolean: true atau false)

Date/Number Operators

  • greater_than - Greater than
  • greater_than_equal - Greater than or equal
  • less_than - Less than
  • less_than_equal - Less than or equal

Logical Operators

  • and - Multiple conditions (AND)
  • or - Multiple conditions (OR)

Contoh penggunaan logical operators:

where[or][0][type][equals]=news&where[or][1][type][equals]=blog

Best Practices

  1. Pagination: Selalu gunakan limit untuk membatasi jumlah data yang diambil, terutama untuk list endpoints.

  2. Depth untuk Relationships:

    • Gunakan depth=0 jika hanya perlu ID relationships
    • Gunakan depth=1 untuk populate first-level relationships (author, image, logo)
    • Gunakan depth=2 untuk populate nested relationships (author dengan image-nya)

  3. Sorting: Gunakan sort parameter untuk mengurutkan hasil, contoh:

    • -publishedDate untuk newest first
    • publishedDate untuk oldest first
    • title untuk alphabetical ascending
    • -title untuk alphabetical descending

  4. Filtering: Kombinasikan multiple filters untuk mendapatkan hasil yang lebih spesifik.

  5. Error Handling: Payload akan mengembalikan status code:

    • 200 - Success
    • 404 - Not found (untuk single item endpoints)
    • 400 - Bad request (invalid query parameters)
    • 500 - Server error

Rate Limiting

Saat ini tidak ada rate limiting yang dikonfigurasi. Namun disarankan untuk:

  • Menggunakan pagination yang wajar (limit maksimal 100 per request)
  • Mengimplementasikan caching di frontend untuk mengurangi request berulang
  • Menggunakan depth parameter dengan bijak (semakin besar depth, semakin berat response)