Data API

Data API داده های عمومی وبلاگ را برمی گرداند.

• هیچ کلید API مورد نیاز نیست.
• همه پاسخ ها در قالب JSON هستند.
• همه نقاط پایانی از روش HTTP GET استفاده می کنند.
• مسیر پایه: https://blog.taptik.ir/api/data/v0/{subdomain} است
• به عنوان مثال، اگر وبلاگ شما در https://blog.example.com است، مسیر پایه است https://blog.taptik.ir/api/data/v0/example
  • زیر دامنه وبلاگ خود را جایگزین {subdomain} کنید.

نقاط پایانی

تک شی

• /post - یک پست/صفحه
• /tag
• /author
• /blog- تنظیمات وبلاگ

چند شیء

• /posts
• /posts/search - جستجوی پست ها
• /tags
• /authors

پاسخ

برای نقاط پایانی تک شی، پاسخ یک شی است. به عنوان مثال، نقطه پایانی /post یک شی Post را برمی گرداند (برای تعاریف شی به زیر مراجعه کنید).

// A Post Object
{
    "id": 1000,
    "slug": "post",
    ...
}

برای نقاط پایانی چند شی، پاسخ به این صورت است:

{
    "data": [{}, {}], // array of objects
    "pagination": {} // a Pagination object
}

درخواست

نقاط پایانی تک شی

برای /post ، /tag ، و /author

نقطه پایانی /blog فقط language و keys را به عنوان ورودی می گیرد.

نقاط پایانی چند شی

/posts ، /posts/search ، /tags ، و /authors

نقطه پایانی /posts/search علاوه بر پارامترهای فوق دارای یک پارامتر search نیز می باشد.

را /tags نقطه پایانی اختیاری دارد visibility پارامتر برای فیلتر کردن برچسب ها بر اساس قابلیت مشاهده. توجه داشته باشید که برچسب های خصوصی قرار نیست در وبلاگ به صورت عمومی نشان داده شوند. آنها فقط باید برای اهداف داخلی استفاده شوند (مثلاً: نمایش/پنهان کردن ویجت در وبلاگ در صورتی که برچسب در پست موجود باشد).

1. پارامتر language

اگر وبلاگ شما دارد چندین زبان، می توانید تنظیم کنید language پارامتر یک کد زبان (مثلاً: en, fr) یک زبان در وبلاگ شما. اگر این پارامتر ارائه نشده باشد، از زبان اصلی وبلاگ استفاده می شود. از آن زبان برای بومی سازی رشته ها در پست ها، نویسندگان، برچسب ها و وبلاگ استفاده می شود.

2. پارامتر limit

از پارامتر limit می توان برای محدود کردن تعداد رکوردهای برگشتی در نقاط پایانی چند شی استفاده کرد. پیش فرض 25 است. حداکثر 250 است.

3. پارامتر page

از پارامتر page می توان برای صفحه بندی نتایج استفاده کرد. این در ترکیب با پارامتر حد کار می کند. مقدار پیش فرض 1 است.

To get the first 20 results: /posts?limit=20 To get the next 20 results (page 2):
/posts?limit=20&page=2

4. پارامتر filter

مثال: (published_at > 1639665890 & published_at < 1639695890) | is_featured=true

Data API ما از Laravel FilterQ در زیر هود استفاده می کند که به شما امکان می دهد منطق پیشرفته مانند مثال بالا را با استفاده از عملگرهای مقایسه و منطقی بنویسید.

یک شرط از سه بخش تشکیل شده است:

• key
• operator
• value

اپراتورها

• = - برابر است
• != - برابر نیست
• > - بیشتر از
• < - کمتر از
• >= - بزرگتر یا مساوی است
• <= - کمتر یا مساوی است

ارزش ها

• null
• bool: true یا false
• رشته: 'hello' یا hello
  • رشته های بدون نقل قول باید با [a-zA-Z_][a-zA-Z0-9_-]+ مطابقت داشته باشند و نمی توانند true ، false ، یا null باشند.
• اعداد: 250, -250,2.5

عملگرهای منطقی

شما می توانید از عملگرهای منطقی برای ترکیب چند شرط استفاده کنید.

• | - OR
• & - و

اگر به جزئیات بیشتری نیاز دارید، لطفاً به مستندات FilterQ Expressions مراجعه کنید.

کلیدهای پشتیبانی شده برای فیلتر کردن

مقادیر تاریخ

در اینجا برخی از مقادیر معتبر برای کلیدهای تاریخ آورده شده است.

• '2022-01-01'
• 'yesterday'
• 'first day of this year'
• 'last day of next month'
• '+1 day'
• '-1 week'
• 'next Thursday'
• 1639655890 - مهر زمانی یونیکس

به عنوان مثال: در نقطه پایانی /posts ، می توانید از published_at>'-7 days' برای دریافت پست های منتشر شده در 7 روز گذشته استفاده کنید.

نمونه های فیلترینگ

برای دریافت پست های نوشته شده توسط الکس:

// filter
author.slug=alex

// URL-encoded
/posts?filter=author.slug%3Dalex

برای دریافت پست های ویژه:

// filter
is_featured=true

// URL-encoded
/posts?filter=is_featured%3Dtrue

برای دریافت پست هایی با تگ audio یا video:

// filter
tag.slug=audio|tag.slug=video

// URL-encoded
/posts?filter=tag.slug%3Daudio%7Ctag.slug%3Dvideo

برای دریافت برچسب هایی که حداقل 5 پست دارند:

// filter
posts_count>=5

// URL-encoded
/tags?filter=posts_count%3E%3D5

برای دریافت نویسندگانی که بعد از ۱ ژانویه ۲۰۲۰ اضافه شده‌اند:

// filter
created_at>='2020-01-01'

// URL-encoded
/authors?filter=created_at%3E%3D%272020-01-01%27

برای دریافت پست های منتشر شده در 7 روز گذشته.

// filter
published_at>'-7 days'

// URL-encoded
/posts?filter=published_at%3E%27-7%20days%27

5. پارامتر sort

در اینجا لیستی از مقادیر مرتب سازی پشتیبانی شده وجود دارد. می‌توانید چندین مقدار را به‌عنوان مقادیر جداشده با کاما ترکیب کنید، که سپس به ترتیب مشابه ORDER BY در SQL اجرا می‌شوند.

روش مرتب سازی پیش فرض DESC است. در اینجا چند مثال برای پارامتر مرتب سازی آورده شده است.

• published_at - مرتب شده توسط published_at به ترتیب نزولی
• published_at ASC - مرتب شده توسط published_at به ترتیب صعودی
• is_featured DESC ، published_at DESC - پست‌های ویژه ابتدا، سپس بر اساس زمان انتشار به ترتیب نزولی مرتب شدند. DESC اختیاری است. is_featured ، published_at با قبلی یکسان است.

6. پارامتر keys

از keys می توان برای گنجاندن یا حذف کلیدها از Objectها، مشابه GraphQL استفاده کرد. تمام نقاط پایانی از پارامتر keys پشتیبانی می کنند.

اگر نقطه پایانی /posts را با keys=id,content فراخوانی کنید، اشیاء پست فقط شامل آن دو کلید خواهند بود.

{
    "id": 1000,
    "content": "<p></p>"
}

از ! در ابتدا برای حذف برچسب ها استفاده کنید. به عنوان مثال، keys=!content,description content و description را از شی Post حذف می کند و تمام کلیدهای دیگر شامل می شود.

فرض کنید فقط می خواهید شناسه پست و شناسه برچسب پست ها را دریافت کنید. از keys=id,tags.id استفاده کنید. شما اشیایی مانند این دریافت خواهید کرد.

{
    "id": 1000,
    "tags": [
        {
            "id": 2000
        }
    ]
}

اشیاء

ارسال شی

{
    "id": 1000,

    "created_at": 1639655890,
    "updated_at": 1639655890,
    "published_at": 1639665890,

    "is_featured": false,
    "is_page": false,
    "slug": "hello-world",
    "content": "<p></p>",
    "title": "Hello World",
    "description": "This is a hello world page",
    "url": "https://blog.example.com/hello-world",
    "featured_image_url": "https://example.com/image.png",
    "canonical_url": null,
    "words": 500,
    "code_head": "",
    "code_foot": "",

    "language": language object,
    "variants": [ variant objects ],

    "tags": [ tag objects ],
    "tags_private": [ tag objects ],
    "authors": [ author objects ]
}

شیء را تگ کنید

{
    "id": 2000,
    "created_at": 1639655890,
    "is_private": false,
    "name": "Hello World",
    "description": "Saying hello to the world",
    "slug": "hello-world",
    "url": "https://blog.example.com/tag/hello-world",
    "posts_count": 20,
    "code_head": null,
    "code_foot": "<p>some code</p>",

    "language": language object,
    "variants": [ variant objects ],
}

شی نویسنده

{
    "id": 3000,
    "created_at": 1639655890,
    "slug": "blogger",
    "url": "https://blog.example.com/author/blogger",
    "name": "Blogger",
    "picture_url": "https://example.com/image.png",
    "bio": "I am a blogger",
    "website_url": "https://example.com",
    "location": "France",
    "social": social media object,
    "posts_count": 32,

    "language": language object,
    "variants": [ variant objects ],
}

شی وبلاگ

{
    "subdomain": "alex",
    "name": "My Blog",
    "description": "This is my blog hosted on ویترو بلاگ",
    "logo_url": "https://blog.example.com/media/logo.png",
    "icon_url": "https://blog.example.com/media/icon.png",
    "cover_url": "https://blog.example.com/media/cover.png",
    "url": "https://blog.example.com",
    "social": social media object,
    "nav_header": [
        {
            "name": "Home",
            "url": "/"
        },
        {
            "name": "About",
            "url": "/about"
        }
    ],
    "nav_footer": [
        {
            "name": "Privacy",
            "url": "/privacy"
        }
    ],

    "languages": [ language objects ],

    "code_head": "",
    "code_foot": "",

    "posts_count": 200,

    // the following are blog settings
    // which are used for generating header code, color themes
    // and footer branding
    "seo_indexing": true,
    "color_modes": "light",
    "color_mode_default": "light",

    // for cache busting
    "cache_version_styles": 1,
}

شیء زبان

{
    "id": 1000,
    "code": "en",
    "name": "English",
    "is_primary": true,
    "direction": "ltr"
}

شیء متغیر

یک شیء متغیر حاوی داده‌های یک نوع زبان یک پست، برچسب یا نویسنده است.

{
    "language": {
        "id": 1001,
        "code": "fr",
        "name": "French",
        "is_primary": false,
        "direction": "ltr"
    },
    "url": "https://blog.example.com/fr/hello-world"
}

شی صفحه بندی

یک شی صفحه‌بندی در تمام نقاط پایانی چند شیء گنجانده شده است (/posts ، /authors ، /tags).

{
    "total": 100,
    "pages": 10,
    "limit": 5,
    "page": 1,
    "page_prev": null,
    "page_next": 2,
}

هدف رسانه های اجتماعی

{
    "facebook": null,
    "twitter": "https://twitter.com/HyvorBlogs",
    "linkedin": "https://www.linkedin.com/company/30240435",
    "youtube": null,
    "instagram": null,
    "github": "https://example.com/profile",
    "tiktok": null
}

رسیدگی به خطا

در صورت بروز خطا، کد وضعیت HTTP یک کد وضعیت غیر 200 خواهد بود.

برای خطاهای 4xx، پاسخ یک شی JSON خواهد بود.

{
    "error": "ID is required",
    "error_code": "422"
}

این کدهای HTTP ممکن است:

• 404 یافت نشد - منبع یافت نشد - 404 را می توان در نقاط پایانی تک شی برگرداند زمانی که شی پیدا نشد - مطمئن شوید که ID/Slug (و زبان پست‌ها) درست است
• 422 موجودیت غیرقابل پردازش - ورودی نامعتبر
  • پارامترهای پرس و جو را بررسی کنید
  • جزئیات بیشتر را می توانید در خروجی JSON خطا پیدا کنید

خطاهای 5xx به این معنی است که چیزی از طرف ما اشتباه است. ما را بررسی کنید صفحه وضعیت برای هر خرابی اگر مشکل ادامه پیدا کرد، با ما تماس بگیرید.

صفحات

ما نقطه پایان جداگانه ای برای واکشی نداریم صفحات.

• برای دریافت یک صفحه، با شناسه صفحه یا اسلاگ با نقطه پایانی /post تماس بگیرید.
• برای دریافت چندین صفحه، نقطه پایانی /posts را با پارامتر ?pages=true تماس بگیرید.
• /posts/search از صفحات جستجو پشتیبانی نمی کند.