مرجع API

نمای کلی

گیتی‌یار یک REST API جامع ارائه می‌دهد که به شما امکان می‌دهد وظایف را خودکار کنید، با ابزارهای دیگر انتگریشن بسازید و برنامه‌های سفارشی ایجاد کنید.

احراز هویت

احراز هویت پایه

curl -u "username:password" http://localhost:3000/api/v1/user

توکن دسترسی (توصیه می‌شود)

یک توکن در تنظیمات → برنامه‌ها → تولید توکن جدید ایجاد کنید

curl -H "Authorization: token YOUR_TOKEN" http://localhost:3000/api/v1/user

پارامتر Query

curl http://localhost:3000/api/v1/user?token=YOUR_TOKEN

URL پایه

http://localhost:3000/api/v1

یا دامنه پیکربندی‌شده شما:

https://gityar.example.com/api/v1

Endpoint های API

کاربر

دریافت کاربر احراز هویت‌شده

GET /api/v1/user

پاسخ:

{
  "id": 1,
  "login": "username",
  "full_name": "Full Name",
  "email": "user@example.com",
  "avatar_url": "http://localhost:3000/user/avatar/username",
  "created_at": "2024-01-01T00:00:00Z"
}

دریافت کاربر با نام کاربری

GET /api/v1/users/:username

مخازن

لیست مخازن شما

GET /api/v1/user/repos

لیست مخازن کاربر

GET /api/v1/users/:username/repos

دریافت مخزن

GET /api/v1/repos/:owner/:repo

ایجاد مخزن

POST /api/v1/user/repos

{
  "name": "my-repo",
  "description": "مخزن من",
  "private": false,
  "auto_init": true
}

حذف مخزن

DELETE /api/v1/repos/:owner/:repo

مسائل

لیست مسائل

GET /api/v1/repos/:owner/:repo/issues
GET /api/v1/issues?filter=all

ایجاد مسئله

POST /api/v1/repos/:owner/:repo/issues

{
  "title": "باگ: چیزی خراب است",
  "body": "توضیح دقیق",
  "labels": [1, 2],
  "assignee": "username"
}

دریافت مسئله

GET /api/v1/repos/:owner/:repo/issues/:index

به‌روزرسانی مسئله

PATCH /api/v1/repos/:owner/:repo/issues/:index

{
  "title": "عنوان به‌روز شده",
  "state": "closed"
}

درخواست‌های تغییر

لیست درخواست‌های تغییر

GET /api/v1/repos/:owner/:repo/pulls

ایجاد درخواست تغییر

POST /api/v1/repos/:owner/:repo/pulls

{
  "title": "افزودن ویژگی جدید",
  "body": "توضیح تغییرات",
  "head": "feature-branch",
  "base": "main"
}

Merge درخواست تغییر

POST /api/v1/repos/:owner/:repo/pulls/:index/merge

سازمان‌ها

لیست سازمان‌های شما

GET /api/v1/user/orgs

دریافت سازمان

GET /api/v1/orgs/:org

ایجاد سازمان

POST /api/v1/orgs

{
  "username": "my-org",
  "full_name": "سازمان من"
}

وب‌هوک‌ها

لیست وب‌هوک‌های مخزن

GET /api/v1/repos/:owner/:repo/hooks

ایجاد وب‌هوک

POST /api/v1/repos/:owner/:repo/hooks

{
  "type": "gitea",
  "config": {
    "url": "https://example.com/webhook",
    "content_type": "json",
    "secret": "your-secret"
  },
  "events": ["push", "issues"],
  "active": true
}

صفحه‌بندی

تمام endpoint های لیست از صفحه‌بندی پشتیبانی می‌کنند:

GET /api/v1/user/repos?page=2&limit=20

Header های پاسخ شامل:

• X-Page: شماره صفحه فعلی
• X-PerPage: موارد در هر صفحه
• X-Total-Count: کل موارد

محدودیت نرخ

درخواست‌های API برای جلوگیری از سوء استفاده محدود می‌شوند.

Header ها:

• X-RateLimit-Limit: حداکثر درخواست در هر ساعت
• X-RateLimit-Remaining: درخواست‌های باقیمانده
• X-RateLimit-Reset: زمانی که محدودیت بازنشانی می‌شود

پاسخ‌های خطا

400 Bad Request

{
  "message": "درخواست نامعتبر",
  "url": "http://localhost:3000/api/v1"
}

401 Unauthorized

{
  "message": "غیرمجاز"
}

404 Not Found

{
  "message": "مخزن یافت نشد",
  "url": "http://localhost:3000/api/v1"
}

422 Unprocessable Entity

{
  "message": "اعتبارسنجی ناموفق",
  "errors": [
    {
      "resource": "Repository",
      "field": "name",
      "code": "invalid"
    }
  ]
}

مثال‌های کد

Python

import requests

# احراز هویت
headers = {
    'Authorization': 'token YOUR_TOKEN'
}

# لیست مخازن
response = requests.get(
    'http://localhost:3000/api/v1/user/repos',
    headers=headers
)

repos = response.json()
for repo in repos:
    print(repo['full_name'])

# ایجاد مسئله
response = requests.post(
    'http://localhost:3000/api/v1/repos/owner/repo/issues',
    headers=headers,
    json={
        'title': 'گزارش باگ',
        'body': 'توضیح دقیق'
    }
)

JavaScript (Node.js)

const axios = require('axios');

const client = axios.create({
  baseURL: 'http://localhost:3000/api/v1',
  headers: {
    'Authorization': 'token YOUR_TOKEN'
  }
});

// لیست مخازن
async function listRepos() {
  const response = await client.get('/user/repos');
  return response.data;
}

// ایجاد مسئله
async function createIssue(owner, repo, issue) {
  const response = await client.post(
    `/repos/${owner}/${repo}/issues`,
    issue
  );
  return response.data;
}

cURL

# دریافت اطلاعات کاربر
curl -H "Authorization: token YOUR_TOKEN" \
  http://localhost:3000/api/v1/user

# ایجاد مخزن
curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-repo","description":"مخزن من"}' \
  http://localhost:3000/api/v1/user/repos

مراحل بعدی

• وب‌هوک‌ها را کاوش کنید
• درباره Git LFS بیاموزید
• درباره مهاجرت بخوانید