Yaml File#Path - Developer

Asset Publisher

null Yaml File#Path

ج) بخش Paths (endpoints):

در این مثال، path های معتبر ـ که از طریق آنها می‌توان دیتا را مشاهده و یا ویرایش کرد ـ به صورت زیر تعریف شده است:

/vitamins

/vitamins/{vitaminId}

 

برای هر یک از دو مسیر فوق، متدهایی و برای هر متد پارامترهایی تعریف شده است که در جدول زیر آمده است :

PathMethodResponse
/vitamins get

Retrieves the list of vitamins. Results can be paginated, filtered, searched, and sorted

Parameters : filter(string) _ page(integer) _ pageSize(integer) _ search(string) _ sort(string)

response :  an array as Vitamin via json file  ($ref: "#/components/schemas/Vitamin")

/vitaminspost

Create a new vitamin.

request body :  new Vitamin record via a json file ($ref: "#/components/schemas/Vitamin" )

response :  new inserted Vitamin via json file ($ref: "#/components/schemas/Vitamin")

/vitamins/{vitaminId}get

Retrieves the vitamin via its ID

Parameters : vitaminId(string)

response : requested Vitamin record ($ref: "#/components/schemas/Vitamin")

/vitamins/{vitaminId} put

Replaces the vitamin with the information sent in the request body. Any missing fields are deleted, unless they are required.

Parameters : vitaminId(string)

request body : new data for Vitamin record via a json file ($ref: "#/components/schemas/Vitamin" )

response : requested Vitamin record ($ref: "#/components/schemas/Vitamin")

/vitamins/{vitaminId} patch

Replaces the vitamin with the information sent in the request body. Any missing fields are deleted, unless they are required.

Parameters : vitaminId(string)

request body : new data for Vitamin record via a json file ($ref: "#/components/schemas/Vitamin" )

response : requested Vitamin record ($ref: "#/components/schemas/Vitamin")

/vitamins/{vitaminId} delete

Deletes the vitamin/mineral and returns a 204 if the operation succeeds.

Parameters : vitaminId(string)

response : ""

 

به صورت کلی یکی از چهار عمل زیر از طریق بخش UI مورد درخواست خواهد بود :

۱) بازیابی (مشاهده) داده‌ها به صورت موردی (با اخذ کلید رکورد به عنوان پارامتر) یا جمعی که در هر دو متد get استفاده می‌شود.

۲) ایجاد یک رکورد جدید به روش get  یا post (که معمولا از روش post استفاده می‌شود)

۳) به روزرسانی یک رکورد خاص به روش put و یا patch.

۴) حذف یک رکورد خاص (delete).

 

نکته مهم : وقتی این مسیرها تعیین شد، عمل buildREST انجام می‌شود و متدهای لازم در ماژول impl ساخته می‌شود. اما این متدها خالی است و این ما هستیم که باید با کدهای جاوا مشخص کنیم که با فراخوانی هر کدام از pathهای فوق، دقیقا چه آیتمهایی از محتویات بسته request خوانده شود، بر اساس آن چه رکودهایی از بانک اطلاعاتی بازیابی شود و چه رکوردهایی تغییر داده شود و در ادامه چه چیزی به صورت فایل json برگردانده شود.


ما از فریم ورک لایفری و OpenAPI برای همه path ها استفاده می‌کنیم و این می‌تواند response های مختلفی شامل موارد موفقیت آمیز و یا خطا وجود داشته باشد. از آنجا که لایفری از این موارد مراقبت می‌کند، ما باید دقت خود را فقط روی response های موفق (کد 200) متمرکز کنیم.

 

مسیر معرفی شده در قسمت path ، تنها path این مثال برای بازیابی رکورد است. به بیان ساده‌تر، در اینجا تعیین می‌کنیم که اگر در حالتی که این پروژه لایفری در حال اجرا باشد، با استفاده از curl و یا postman این path را پس از localhost:8080 بزنیم ، یک فایل json حاوی یک رکورد vitamin به عنوان پاسخ برگردانده می‌شود که در آن {entityId} معرف شناسه آن رکورد است.

paths:

  "/vitamins/{vitaminId}":
    get:
      operationId: getVitamin
      tags: ["Vitamin"]
      description: Retrieves the vitamin/mineral via its ID.
      parameters:
        - name: vitaminId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Vitamin"
            application/xml:
              schema:
                $ref: "#/components/schemas/Vitamin"

 

url درخواست،از طریق متد get یک آبجکت از نوع Vitamin را برمی‌گرداند. این نقطه را یک endpoint می‌نامند.

توجه: عبارت درج شده جلوی tags  (خط دوم) مهم است و با نوع داده‌ای که برمی‌گرداند مطابقت دارد. این نوع داده، باید در قسمت schemas بخش components معرفی شده باشد.

REST Builder متدی را در کلاس  EntityResourceImpl.java ایجاد می‌کند.

در این مثال فقط متد get برای بازیابی داده آورده شد اما در پروژه پرتلت درس‌افزار، علاوه بر این اندپوینت، اندپوینتهای متعدد دیگری هم برای تغییر داده‌ها ، درج داده جدید و حذف داده قبلی نیز تشریح شده است. بنابراین برای درک بهتر فایل yaml، در ادامه این صفحه، متدهای مربوط به مدل CuorseTerm و برخی دیگر از مدلهای پرتلت درس‌افزار مورد بررسی قرار می‌گیرد:


مثال : pathهای معرفی شده در فایل yaml پروژه درس‌افزار مربوط به مدل CourseTerm

 

۱) متد delete برای حذف یک آیتم (رکورد)

 

    "/course-terms/{courseTermId}":
        delete:
            description:
                Deletes the courseTerm
            operationId: deleteCourseTerm
            parameters:
                - in: path
                  name: courseTermId
                  required: true
                  schema:
                      format: int64
                      type: integer
            responses:
                204:
                    content:
                        application/json: {}
                        application/xml: {}
                    description:
                        ""
            tags: ["CourseTerm"]


۲) متد get برای بازیابی یک آیتم (رکورد)

 

        get:
            description:
                Retrieves the CourseTerm by courseTermId
            operationId: getCourseTerm
            parameters:
                - in: path
                  name: courseTermId
                  required: true
                  schema:
                      format: int64
                      type: integer
            responses:
                200:
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CourseTerm"
                        application/xml:
                            schema:
                                $ref: "#/components/schemas/CourseTerm"
                    description:
                        "CourseTerms successfully get"
            tags: ["CourseTerm"]

 

۳) متدput برای تغییر محتوای یک  آیتم (رکورد)

        put:
            description:
                Update a courseTerm
            operationId: putCourseTerm
            parameters:
                - in: path
                  name: courseTermId
                  required: true
                  schema:
                      format: int64
                      type: integer
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/CourseTerm"
                    application/xml:
                        schema:
                            $ref: "#/components/schemas/CourseTerm"
            responses:
                200:
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/CourseTerm"
                        application/xml:
                            schema:
                                $ref: "#/components/schemas/CourseTerm"
                    description:
                        "CourseTerm successfully updated"
            tags: ["CourseTerm"]

تفاوت put و patch :
برای تغییر و جایگزینی داده، از put استفاده می‌کنیم و هر چه را که درون بسته درخواست (requestBody) آمده باشد، با محتوای رکورد مورد نظر جایگزین می‌کنیم. هر فیلدی هم که در درخواست ذکری از آن نشده باشد، در هنگام جایگزینی برابر balnk و یا null می‌شود. محتوای response نیز دربرگیرنده رکورد تغییریافته است.
اما اگر بخواهیم فیلدهایی که در بسته درخواست request ذکری از آنها به میان نیامده و غایب هستند، دست نخورده باقی بمانند و مقدار آنها در بانک اطلاعاتی برابر balnk و یا null نشود از دستور patch استفاده می‌کنیم.  محتوای response نیزمثل دستور put  دربرگیرنده رکورد تغییریافته است.

۴) بازیابی لیست رکوردهای «منابع» (فایلهای) مربوط به تمرین
path زیر در پروژه lms تعریف شده و برای بازیابی لیست رکوردهای منابع مربوط به تمرینهاست که در جدول resources نگهداری می‌شوند. در این روش از paging استفاده می‌شود تا داده‌ها را یک‌جا و به صورت لیست کامل برگرداند.

    "/sites/{siteId}/assignments/{assignmentId}/resources":
        get:
            description:
                Retrieves the Resources of assignment by assignmentId
            operationId: getResourcesByAssignmentIdPage
            parameters:
                - in: path
                  name: siteId
                  required: true
                  schema:
                      format: int64
                      type: integer
                - in: path
                  name: assignmentId
                  required: true
                  schema:
                      format: int64
                      type: integer
                - in: query
                  name: filter
                  schema:
                      type: string
                - in: query
                  name: page
                  schema:
                      type: integer
                - in: query
                  name: pageSize
                  schema:
                      type: integer
                - in: query
                  name: search
                  schema:
                      type: string
                - in: query
                  name: sort
                  schema:
                      type: string
            responses:
                200:
                    content:
                        application/json:
                            schema:
                                items:
                                    $ref: "#/components/schemas/Resource"
                                type: array
                        application/xml:
                            schema:
                                items:
                                    $ref: "#/components/schemas/Resource"
                                type: array
                    description:
                        "Resourcea successfully get"
            tags: ["Resource"]


۵) متد ایجاد رکورد برای ایجاد یک منبع (فایل ـ لینک ـ یا ..) و انتساب آن به یک رکورد تمرین
با استفاده از path قبلی و البته با متد POST  می‌توانیم یک شی (رکورد) منبع جدید ایجاد کنیم.

 

        post:
            description:
                Creates a Resource and add to assignment.
            operationId: addResourceToAssignment
            parameters:
                - in: path
                  name: siteId
                  required: true
                  schema:
                      format: int64
                      type: integer
                - in: path
                  name: assignmentId
                  required: true
                  schema:
                      format: int64
                      type: integer
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            properties:
                                file:
                                    format: binary
                                    type: string
                                resource:
                                    $ref: "#/components/schemas/Resource"
                            type: object
            responses:
                200:
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Resource"
                        application/xml:
                            schema:
                                $ref: "#/components/schemas/Resource"
                    description:
                        "Resource successfully updated"
            tags: ["Resource"]