Co to jest RAML?

RAML, który jest skrótem od “RESTful API Modeling Language”, jest językiem opartym na YAML do opisywania RESTful API. Jest to plan przed opracowaniem API który ułatwia zarówno programistom, jak i interesariuszom zrozumienie struktury i zachowania API.

Czym są typy danych?

Typy danych służą do określania struktury lub typu danych wymienianych między klientem a serwerem. Pozwala to na walidację ładunków żądań i odpowiedzi oraz utrzymanie standardów ładunku.

Wbudowane typy danych

RAML zawiera kilka wbudowanych lub prymitywnych typów danych, które reprezentują podstawowe typy wartości. Niektóre z typowych wbudowanych typów danych obejmują:

• String: Reprezentuje dane tekstowe.
• Liczba: Reprezentuje wartości numeryczne.
• Integer: Reprezentuje liczby całkowite.
• Boolean: Reprezentuje wartości true lub false.
• Date-Only: Reprezentuje datę bez składnika czasu.
• Tylko czas: Reprezentuje czas bez składnika daty.
• DateTime: Reprezentuje datę i godzinę.

Typy danych zdefiniowane przez użytkownika

W RAML można również definiować niestandardowe lub zdefiniowane przez użytkownika typy danych. Typy te mogą mieć określone właściwości z własnymi typami danych. Pozwala to na tworzenie ustrukturyzowanych komponentów wielokrotnego użytku dla interfejsu API.

Przypadek użycia

Proszę utworzyć RAML z pojedynczym zasobem z różnymi typami i formatami danych i opublikować go na Exchange.

Cele

• Utworzenie specyfikacji RAML.
• Tworzenie plików typu danych.
• Proszę utworzyć zasób /user i dodać wymagane informacje.
• Proszę zweryfikować punkty końcowe za pomocą szyderczych usług.
• Publish to Exchange.

Krok 1: Tworzenie specyfikacji RAML

• Proszę utworzyć konto na platformie Anypoint.
• Przejść do Design Center i utworzyć specyfikację RAML.
• Proszę nadać specyfikacji odpowiednią nazwę.

Krok 2: Tworzenie plików DataType

• Proszę utworzyć folder “dataTypes” w sekcji plików.
• Proszę utworzyć folder dataTypes i dodać typy danych żądania i odpowiedzi, jak poniżej.
  • jsonDataTypeOne
  • jsonDataTypeTwo
  • xmlDataType
  • responseDataType

jsonDataTypeOne

#%RAML 1.0 DataType

type: object
properties:
 name:
   type: string
   example: "Caroline"
 age:
   type: number
   example: 22
 active:
   type: boolean
   example: true

jsonDataTypeTwo

#%RAML 1.0 DataType


type: object
properties:
 name:
   type: string
   example: "Caroline"
 age:
   type: number
   example: 22
 address:
   type: string
   example: "145 Main St, Dallas, TX"

xmlDataType

#%RAML 1.0 DataType

type: object
properties:
 top:
   type: object
   properties:
     abc:
       xml:
         attribute: true
         name: abc
     xmlNamespace:
       xml:
         attribute: true
         namespace: http://google.com
     node:
       type: string
       example:
         <xml>
           <top abc="123" xmlns="http://google.com">
             <node>12345</node>
           </top>
         </xml>

responseDataType

#%RAML 1.0 DataType

type: object
properties:
 message:
   type: string
   example: "success"
 payload:
   type: object
   example: {}

Krok 3: Tworzenie zasobów/użytkowników

Poniżej znajduje się przykładowa specyfikacja RAML.

#%RAML 1.0
title: test

types:
 jsonTypeOne: !include dataTypes/jsonDataTypeOne.raml
 jsonTypeTwo: !include dataTypes/jsonDataTypeTwo.raml
 xmlType: !include dataTypes/xmlDataType.raml
 responseType: !include  dataTypes/responseDataType.raml

/users:
 post:
   body:
     application/json:
       type: jsonTypeOne | jsonTypeTwo
     application/xml:
       type: xmlType
   responses:
     200:
       body:
         application/json:
           type: responseType

W powyższej specyfikacji RAML symbol “|” jest używany w typie ciała, co oznacza, że może on akceptować zarówno jsonTypeOne, jak i jsonTypeTwo. Oprócz tego możemy również wysłać xmlType.

Krok 4: Weryfikacja punktów końcowych przy użyciu Mocking Services

Na powyższym obrazku widzimy, że akceptuje zarówno typ json, jak i xml. Pozwala również użytkownikowi wybrać pomiędzy jsonTypeOne lub jsonTypeTwo.

Krok 5: Publikowanie w Exchange

Gdy specyfikacja RAML jest gotowa i zweryfikowana przy użyciu usług mockowania, można opublikować specyfikację w Anypoint Exchange. Publikacja w Exchange umożliwi Państwa użytkownikom weryfikację punktów końcowych przed rozpoczęciem implementacji.

Podsumowanie

Podsumowując, pojedynczy zasób może mieć różne typy danych o różnych formatach, a użytkownicy mogą je wdrażać zgodnie ze swoimi wymaganiami.