لطفا صبر کنید ...

JSON API چیست و چه کاربردی دارد؟

الهام غایب

توسط الهام غایب

دیدگاه ها: 0
بازدید ها : 264
رایگان
هدف ما این است که شما، در بالاترین سطح طراحی و توسعه وب باشید.

ثبت نام کنید

JSON API در سال ۲۰۱۳ توسط یهودا کاتز پیش نویس شده و در سال ۲۰۱۵ به بازار عرضه شد و هدف آن کارآمدتر کردن فراخوانی API است. با لیداوب همراه باشید.


شما می‌توانید داده‌های مورد نیاز خود را واکشی کنید یا ویژگی‌های یا روابط جدید را براساس تغییر نیازهای خود اضافه یا حذف کنید. این ویژگی باعث به حداقل رسیدن میزان داده و مسیرهای رفت و برگشت در زمان فراخوانی API می‌شود. مستندات JSON API مانند هر فرمت API دیگری کار می‌کند یعنی شما یک درخواست به یک پایانه ارسال می‌کنید و سند خود را دریافت می‌کنید. مشخصات JSON API مشخص می‌کند چگونه منابع ساختار بندی شده‌اند. این ساختار به نرمالیزه کردن نحوه استفاده شما از API کمک می‌کند. برای مثال، وقتی شما از طریق یک درخواست ساده GET، یک برای article فراخوانی ارسال می‌کنید:

GET /articles HTTP/1.1 
Accept: application/vnd.api+json

پاسخی دریافت می‌کنید که باید مشابه زیر باشد:

// ...  
{  
    "type": "articles",  
    "id": "1",  
    "attributes": {  
        "title": "Rails is Omakase"  
    },  
    "relationships": {  
        "author": {  
            "links": {  
                "self": "https://example.com/articles/1/relationships/author",  
                "related": "https://example.com/articles/1/author"  
            },  
            "data": {  
                "type": "people",  
                "id": "9"  
            }  
        }  
    },  
    "links": {  
        "self": "https://example.com/articles/1"  
    }  
} // ...

ویژگی‌های JSON API

به اندازه کافی ساده به نظر می‌رسد. رابطه مولف یا author شامل لینکی به خود رابطه و برخی از اطلاعات پایه در مورد رابطه است. با استفاده از لینک‌ها در سند می‌توانید اطلاعات را در منابع مربوطه بازیابی کنید. اما این فقط بخشی از ویژگی‌های JSON API است. ویژگی‌های فراوان دیگری هم وجود دارند که باعث می‌شوند عاشق استفاده از آن شوید.

استفاده از اسناد مرکب

برای کاهش تعداد درخواست‌های HTTP، سرورها ممکن است اجازه دهند که پاسخ‌ها شامل منابع مرتبط به همراه منابع درخواست شده باشند. این پاسخ‌ها را «اسناد مرکب» می‌نامند. یک سند مرکب یک منبع است که شامل داده‌های روابط می‌باشد. برای مثال، در زمان درخواست یک مقاله که در قسمت بالا نشان داده شد، باید داده‌های author هم گنجانده شود تا نیاز به فراخوانی دوم برای واکشی مولف مقاله نداشته باشید.

به چند دلیل این ویژگی فوق العاده است. دریافت داده‌های کامل منبعی که می‌خواهید استفاده کنید از یک پایانه خاص امکان ندارد مگر آنکه با برنامه نویسی این امکان ایجاد شده باشد. در سمت سرور، کش کردن و لغو یک درخواست مانند این ساده است. نگاهی به این نمونه بیاندازید که یک مجموعه از یک سند را بازمی‌گرداند:

{  
    "data": [{  
        "type": "articles",  
        "id": "1",  
        "attributes": {  
            "title": "JSON API paints my bikeshed!"  
        },  
        "links": {  
            "self": "https://example.com/articles/1"  
        },  
        "relationships": {  
            "author": {  
                "links": {  
                    "self": "https://example.com/articles/1/relationships/author",  
                    "related": "https://example.com/articles/1/author"  
                },  
                "data": {  
                    "type": "people",  
                    "id": "9"  
                }  
            },  
            "comments": {  
                "links": {  
                    "self": "https://example.com/articles/1/relationships/comments",  
                    "related": "https://example.com/articles/1/comments"  
                },  
                "data": [{  
                    "type": "comments",  
                    "id": "5"  
                }, {  
                    "type": "comments",  
                    "id": "12"  
                }]  
            }  
        }  
    }],  
    "included": [{  
        "type": "people",  
        "id": "9",  
        "attributes": {  
            "first-name": "Dan",  
            "last-name": "Gebhardt",  
            "twitter": "dgeb"  
        },  
        "links": {  
            "self": "https://example.com/people/9"  
        }  
    }, {  
        "type": "comments",  
        "id": "5",  
        "attributes": {  
            "body": "First!"  
        },  
        "relationships": {  
            "author": {  
                "data": {  
                    "type": "people",  
                    "id": "2"  
                }  
            }  
        },  
        "links": {  
            "self": "https://example.com/comments/5"  
        }  
    }, {  
        "type": "comments",  
        "id": "12",  
        "attributes": {  
            "body": "I like XML better"  
        },  
        "relationships": {  
            "author": {  
                "data": {  
                    "type": "people",  
                    "id": "9"  
                }  
            }  
        },  
        "links": {  
            "self": "https://example.com/comments/12"  
        }  
    }]  
}

اگر به ویژگی include نگاه کنید تمام منابع مرتبط برای مقاله را در آن خواهید دید. هر سند دارای یک خصوصیت type است که مشخص می‌کند کدام نوع منبع بازگردانده شود و یک لینک به پایانه برای آن سند ایجاد می‌کند. شاید اشاره به رابطه author در article توسط id و type و بارگذاری منبع people از تگ included عجیب به نظر برسد. اما زمانی را تصور کنید که چند article به یک author اشاره می‌کنند، سند تنها شامل افراد اشاره شده در داده‌های included است.

گنجاندن منابع مرتبط

در مثال بالا سرور شامل تمام روابط در پاسخ است اما شاید نخواهید این ویژگی به صورت پیش‌فرض وجود داشته باشد چون این باعث بالا رفتن حجم پاسخ می‌شود. به همین دلیل، راهی برای مشخص کردن اینکه کدام روابط باید در پاسخ قرار بگیرند وجود دارد. برای مثال، اگر فقط نیاز داشته باشید رابطه author گنجانده شود، می‌تواند پایانه‌ای با پارامتر درخواست include را فراخوانی کنید. این درخواست به سرور می‌گوید تا فقط روابط مشخص را با پاسخ ارسال کند:

GET /articles/1?include=author HTTP/1.1
Accept: application/vnd.api+json

اگر چند رابطه نیاز داشته باشید روابط را با کاما (,) جدا کنید. در زمان تعریف include می‌توانید روابط تو در تو را هم درخواست دهید. برای مثال، وقتی comments و author کامنت‌ها را می‌خواهید، می‌توانید comments.author را درخواست کنید:

GET /articles/1?include=author,comments.author HTTP/1.1
Accept: application/vnd.api+json

این انعطاف پذیری باعث می‌شود واکشی منابع درست به سادگی انجام شده و نتایج مورد نیاز را به دست آورید.

تفکیک فیلدها

وقتی از اسناد مرکب استفاده می‌کنید، درخواست شما می‌تواند بزرگ و سریع باشد. مخصوصا وقتی روابط در برگرفته، حاوی داده‌های زیادی باشد. بیشتر وقت‌ها، شما نیازی به تمام ویژگی‌های تعریف شده در منابع ندارید بلکه فقط مواردی مانند نام نویسنده را می‌خواهید. JSON API تفکیک فیلدها را برای این مورد ارائه می‌دهد.

می‌توانید فیلدهایی که واکشی می‌شوند را با قرار دادن پارامتر درخواست برای فیلدها مشخص کنید. فرمت آن به صورت fields[TYPE] است. بنابراین، می‌توانید به ازای هر منبع، فیلدهایی که نیاز دارید را مشخص کنید:

GET /articles?include=author&fields[articles]=title,body&fields[people]=name HTTP/1.1
Accept: application/vnd.api+json

این فراخوانی می‌تواند شامل title و body منابع مقاله و فیلد name از منبع افراد شود.

سایر ویژگی ها

سرورها ویژگی‌های دیگری را هم پیاده سازی می‌کنند که با مشخصات، تعریف می‌شود. این ویژگی‌ها شامل در برگیری، دسته بندی، صفحه بندی و فیلتر کردن.

دسته بندی

اگر سرور از آن پشتیبانی کند، می‌توانید رکوردهای خود را با استفاده پارامتر درخواست sort ، دسته بندی کنید. دسته بندی به صورت پیش‌فرض در ترتیب صعودی است. برای ایجاد ترتیب نزولی می‌توانید را به فیلد اضافه کنید:

GET /articles?sort=-created,title HTTP/1.1
Accept: application/vnd.api+json

صفحه بندی

اگر سرور از صفحه بندی پشتیبانی کند، چند ویژگی متا با اطلاعات متا در اختیار شما قرار می‌گیرد. سرور می‌تواند تصمیم بگیرد چگونه خود را صفحه بندی کند، از طریق صفحه شروع یا شماره صفحات. یک نمونه از پیاده سازی از لینک‌های مورد نیاز به سایر صفحات استفاده کرده و شامل چند متا دیتا و متا تگ است:

{
  links: {  
    first: "https://example.com/articles?page=1",  
    last: "https://example.com/articles?page=262",  
    prev: "https://example.com/articles?page=261",  
    next: null  
  }, 
  meta: {  
    current_page: 262,  
    from: 3916,  
    last_page: 262,  
    per_page: 15,  
    to: 3924,  
    total: 3924  
  }
}

فیلتر کردن

مشخصات اطلاعات کمی در مورد فیلتر کردن ارائه می‌دهد. فقط عنوان می‌کند که ممکن است پارامتری وجود داشته باشد که filter نامیده شده و برای انجام فیلترینگ روی سرور به کار برده می‌شود.

ایجاد، به روز رسانی و حذف منابع

وقتی شما ساختار سند را متوجه شوید، ایجاد و به روز رسانی منابع کار آسانی خواهد بود. این کار به http استاندارد برای مخابره اقدام مورد نظر درخواست نیاز دارد. GET برای واکشی، POST برای ایجاد، PATCH برای به روز رسانی و DELETE برای حذف منابع می‌باشد.

ایجاد منابع

POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "photos",
    "attributes": {
      "title": "Ember Hamster",
      "src": "https://example.com/images/productivity.png"
    },
    "relationships": {
      "photographer": {
        "data": { "type": "people", "id": "9" }
      }
    }
  }
}

این یک نمونه از پست تصویر جدید است. همانطور که می‌بینید رابطه در درخواست در خصوصیت relationship گنجانده شده است.

به روز رسانی منبع

PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "To TDD or Not"
    }
  }
}

در زمان به روز رسانی یک منبع، فیلدهای پست شده با مقادیر جدید به روز رسانی میشوند. مقادیری که در درخواست در برگرفته نشده‌اند به روز رسانی نخواهند شد.

به روز رسانی روابط

به روز رسانی روابط به دو روش امکان پذیر است. روش اول قرار دادن رابطه در درخواست PATCH می‌باشد. همین روش را پیشتر هم ملاحظه کردید. روش دیگر هم استفاده از پایانه مخصوص relationship می‌باشد:

PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": { "type": "people", "id": "12" }
}

این فراخوانی رابطه to-one را در article به روز رسانی خواهد کرد. اگر می‌خواهید رابطه را حذف کنید، می‌توانید null را به عنوان داده اضافه کنید. اگر می‌خواهید یک رابطه to-many را به روز رسانی کنید، می‌توانید یک آرایه از رابطه را به پایانه ارسال کنید. این باعث می‌شود تمام اعضای رابطه با داده‌های پست خود جایگزین کنید:

PATCH /articles/1/relationships/tags HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": [
    { "type": "tags", "id": "2" },
    { "type": "tags", "id": "3" }
  ]
}

در زمان حذف یک رابطه to-many، فقط یک آرایه خالی به عنوان داده ارسال کنید.

حذف منابع

 در مورد حذف منبع، فقط یک فراخوانی DELETE به پایانه ارسال می‌کنید:

DELETE /photos/1 HTTP/1.1
Accept: application/vnd.api+json

مطالعه مقالات بیشتر در لیداوب:

با کتابخانه آنلاین لیداوب همراه باشید و سایر مقالات ما در زمینه لاراول، برنامه نویسی و طراحی سایت را دنبال کنید.

منبع :

5 از 1 رای

 مطالب مرتبط  

در قسمت زیر مطالبی وجود دارند که با مقاله فعلی مرتبط هستند



متاسفانه فقط اعضای سایت قادر به ثبت دیدگاه هستند

برترین مطالب

آموزش در لیداوب

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

جدیدترین سرویس ما برای دوستان متخصص و خوش بیان در زمینه طراحی وب ارائه شد. این سرویس به شما این امکان را می دهد که به آسانی مقالات و یا ویدیو های آموزشی خود را در لیداوب منتشر کنید. فرصت مناسبی است که بدون داشتن وب سایت و یا وبلاگ و مهم تر از همه بدون هزینه، مطالب خود را در لیداوب منتشر کنید و مهم تر از همه با فروش آنها کسب درآمد کنید. همین حالا شروع کنید و این فرصت استثنایی را از دست ندهید.