آموزش RAML - مسائل ابتدایی

خب حالا میتونی یه فایل درست کنی با پسوند raml که توش یسری اطلاعات کلی وارد میکنی:

#%RAML 1.0
---
title: e-BookMobile API
baseUri: http://api.e-bookmobile.com/{version}
version: v1

به این قسمت از raml فایل بخش root میگن که توضیح دهنده کل API ای هست که داری داکیومنتش میکنی. مثل title و version. توی بخش root میتونی assets هایی رو که تو داکیومنتت استفاده کردی هم معرفی بکنی، مثل: types و traits.

title

میای عنوان کلی API خودتو مشخص میکنی.

baseUri

برای هر فراخوانی API از این baseUri استفاده میشه. پس سعی کنید تا جایی که ممکنه تمیز، ساده و مختصر باشه.

version

توی ورژن میای ورژن API خودتو مشخص میکنی.

وارد کردن Resource ها

به عنوان یه API designer باید در مورد اینکه کاربرا از API تو چجوری میخوان استفاده بکنن فکر بکنی، چونکه تو تعیین کننده این هستی که از API چجوری استفاده بکنن. مثلا تو میدونی که:

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

پس باید collection های مختلفی به عنوان resource هات تعریف بکنی.

تعریف Resource چیه؟

مشخصه یه ریسورس اینه که URI نسبی داره که با / شروع میشه. هر نودی که کلیدش با / شروع میشه و توی root تعریف API هست، یا فرزند یه نود ریسورس هست.

ریسورسی که در root-level تعریف میشه top-level resource هست. کلید نود root-level همون URI ریسورس هست. ریسورسی که به عنوان نود فرزند یه ریسورس دیگه تعریف میشه nested resource هست. کلید nested resource هم URI که بعد از URI ریسورس والد میاد.

در مثال زیر gists یه root-level ریسورس هست و public یه nested resource هست:

#%RAML 1.0
title: GitHub API
version: v3
baseUri: https://api.github.com
/gists:
  displayName: Gists
  /public:
    displayName: Public Gists

پس با به یاد داشتن خواسته های کاربرات باید ۳ تا resource زیر رو بعد از root تعریف بکنی:

/users:
  /authors:
  /books:

نود ها توی raml فایل ممکنه به هر ترتیبی بیان ولی Processor ها باید ترتیب نود های یکسان رو که درون یک نود تعریف شدن حفظ بکنن. مثل resource هایی که تو یه سطح از درخت resource هستن، متد های resource داده شده، پارامتر های متد داده شده و نود های تو یه سطح در یک type مشخص. Processor ها باید ترتیب آیتم ها رو داخل یه ارایه هم حفظ بکنن.

https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#the-root-of-the-document

مثالی که میارم از GitHub v3 هست:

#%RAML 1.0
title: GitHub API
version: v3
baseUri: https://api.github.com
mediaType:  application/json
securitySchemes:
  oauth_2_0: !include securitySchemes/oauth_2_0.raml
types:
  Gist:  !include types/gist.raml
  Gists: !include types/gists.raml
resourceTypes:
  collection: !include types/collection.raml
traits:
securedBy: [ oauth_2_0 ]
/search:
  /code:
    type: collection
    get:

برای دیدن مثال های بیشتر کلیک کنید.

برای دیدن توضیحات بیشتر کلیک کنید.