Introduktion til RAML - RESTful API-modelleringssprog

Denne artikel er en del af en serie: • Introduktion til RAML - RESTful API-modelleringssprog (nuværende artikel) • Fjern afskedigelser i RAML med ressourcetyper og træk

• Modulær RAML ved hjælp af inkluderer, biblioteker, overlejringer og udvidelser

• Definer brugerdefinerede RAML-egenskaber ved hjælp af kommentarer

1. Oversigt

I denne artikel introducerer vi RESTful API Modelling Language (RAML), et leverandørneutralt, åbent specifikationssprog bygget på YAML 1.2 og JSON til beskrivelse af RESTful API'er.

Vi dækker grundlæggende RAML 1.0-syntaks og filstruktur, når vi demonstrerer, hvordan man definerer en simpel JSON-baseret API. Vi viser også, hvordan du forenkler vedligeholdelse af RAML-filer ved hjælp af inkluderer. Og hvis du har ældre API'er, der bruger JSON-skema, viser vi, hvordan du integrerer skemaer i RAML.

Derefter introducerer vi en håndfuld værktøjer, der kan forbedre din rejse til RAML, herunder redigeringsværktøjer, dokumentationsgeneratorer og andre.

Endelig afslutter vi ved at beskrive den aktuelle tilstand for RAML-specifikationen.

2. Definere din API (Oprettelse af .raml fil)

Den API, vi definerer, er ret enkel: givet enhedstyperne Foo, definer grundlæggende CRUD-operationer og et par forespørgselshandlinger. Her er de ressourcer, som vi definerer til vores API:

  • GET / api / v1 / foos
  • POST / api / v1 / foos
  • GET / api / v1 / foos / {id}
  • PUT / api / v1 / foos / {id}
  • SLET / api / v1 / foos / {id}
  • GET / api / v1 / foos / name / {name}
  • GET / api / v1 / foos? Name = {name} & ownerName = {ownerName}

Og lad os definere vores API til at være statsløs ved hjælp af HTTP Basic-godkendelse og leveres krypteret via HTTPS. Lad os endelig vælge JSON til vores datatransportformat (XML understøttes også).

2.1. Indstillinger på rodniveau

Vi starter med at oprette en simpel tekstfil med navnet api.raml (det .raml prefix anbefales; navnet er vilkårligt) og tilføj RAML-versionens overskrift på linje en. På filens rodniveau definerer vi indstillinger, der gælder for hele API:

#% RAML 1.0 titel: Baeldung Foo REST Services API ved hjælp af datatyper version: v1 protokoller: [HTTPS] baseUri: //myapi.mysite.com/api/{version} mediaType: application / json

Bemærk på linje 3 brugen af ​​seler {} omkring ordet “version“. Sådan fortæller vi RAML at “version" henviser til en ejendom og skal udvides. Derfor den faktiske baseUri vil være: //myapi.mysite.com/v1

[Bemærk: version ejendom er valgfri og behøver ikke være en del af baseUri.]

2.2. Sikkerhed

Sikkerhed defineres også på rodniveauet for .raml fil. Så lad os tilføje vores definition af HTTP-grundlæggende sikkerhedsskema:

sikkerhedSkemaer: basicAuth: beskrivelse: Hver anmodning skal indeholde de nødvendige overskrifter til grundlæggende godkendelsestype: Grundlæggende godkendelse beskrevet af By: overskrifter: Autorisation: beskrivelse: Bruges til at sende det Base64-kodede "brugernavn: adgangskode" legitimationsoplysninger type: strengrespons: 401: beskrivelse: | Uberettiget. Enten er det angivne kombination af brugernavn og adgangskode ugyldigt, eller brugeren har ikke adgang til det indhold, der leveres af den anmodede URL.

2.3. Datatyper

Dernæst definerer vi de datatyper, som vores API bruger:

typer: Foo: type: objektegenskaber: id: krævet: sand type: heltal navn: krævet: sand type: streng ejer Navn: krævet: falsk type: streng

Ovenstående eksempel bruger udvidet syntaks til at definere vores datatyper. RAML giver nogle syntaktiske genveje for at gøre vores typedefinitioner mindre detaljerede. Her er den tilsvarende datatypesektion, der bruger disse genveje:

typer: Foo: egenskaber: id: heltal navn: streng ejernavn ?: streng Fejl: egenskaber: kode: heltal besked: streng

Det '?' tegn efter et ejendomsnavn erklærer, at ejendommen ikke er påkrævet.

2.4. Ressourcer

Nu definerer vi top-niveau ressourcen (URI) i vores API:

/ foos:

2.5. URI-parametre

Dernæst udvider vi listen over ressourcer og bygger på vores topniveauressource:

/ foos: / {id}: / name / {name}:

Her definerer seler {} omkring ejendomsnavne URI-parametre. De repræsenterer pladsholdere i hver URI og henviser ikke til RAML-filegenskaber på rodniveau, som vi så ovenfor i baseUri erklæring. De tilføjede linjer repræsenterer ressourcerne / foos / {id} og / foos / name / {name}.

2.6. Metoder

Det næste trin er at definere de HTTP-metoder, der gælder for hver ressource:

/ foos: get: post: / {id}: get: put: delete: / name / {name}: get:

2.7. Forespørgselsparametre

Nu definerer vi en måde at forespørge på foos samling ved hjælp af forespørgselsparametre. Bemærk, at forespørgselsparametre er defineret ved hjælp af den samme syntaks, som vi brugte ovenfor til datatyper:

/ foos: get: beskrivelse: Liste over alle Foos-matchende forespørgselskriterier, hvis de findes; Ellers anfør alle Foos queryParameters: navn ?: streng ejernavn ?: streng

2.8. Svar

Nu hvor vi har defineret alle ressourcerne til vores API, inklusive URI-parametre, HTTP-metoder og forespørgselsparametre, er det tid til at definere de forventede svar og statuskoder. Svarformater defineres typisk med hensyn til datatyper og eksempler.

JSON-skema kan bruges i stedet for datatyper til bagudkompatibilitet med en tidligere version af RAML. Vi introducerer JSON-skema i afsnit 3.

[Bemærk: I nedenstående kodestykker angiver en linje, der kun indeholder tre prikker (...), at nogle linjer springes over for kortfattethed.]

Lad os starte med den enkle GET-operation til / foos / {id}:

/ foos: ... / {id}: get: beskrivelse: Få en Foo efter id-svar: 200: body: application / json: type: Foo-eksempel: {"id": 1, "name": "First Foo" }

Dette eksempel viser, at ved at udføre en GET-anmodning på ressourcen / foos / {id}, vi skulle få matchningen tilbage Foo i form af et JSON-objekt og en HTTP-statuskode på 200.

Sådan definerer vi GET-anmodningen på / foos ressource:

/ foos: get: beskrivelse: Liste over alle Foos-matchende forespørgselskriterier, hvis de findes; Ellers anfør alle Foos-forespørgslerParametre: navn ?: streng ejernavn ?: strengrespons: 200: body: application / json: type: Foo [] eksempel: | [{"id": 1, "name": "First Foo"}, {"id": 2, "name": "Second Foo"}]

Bemærk brugen af ​​firkantede parenteser [] vedhæftet til Foo type. Dette viser, hvordan vi ville definere et responsorgan, der indeholder en matrix af Foo objekter, hvor eksemplet er en matrix med JSON-objekter.

2.9. Anmodningsorgan

Dernæst definerer vi de anmodningsorganer, der svarer til hver POST- og PUT-anmodning. Lad os begynde med at oprette en ny Foo objekt:

/ foos: ... post: beskrivelse: Opret en ny Foo body: applikation / json: type: Foo eksempel: {"id": 5, "name": "Another foo"} svar: 201: body: application / json : type: Foo eksempel: {"id": 5, "name": "Another foo"}

2.10. Statuskoder

Bemærk i eksemplet ovenfor, at når vi opretter et nyt objekt, returnerer vi en HTTP-status på 201. PUT-operationen til opdatering af et objekt vil returnere en HTTP-status på 200 ved hjælp af de samme anmodnings- og svarorganer som POST-operationen.

Ud over de forventede svar og statuskoder, som vi returnerer, når en anmodning er vellykket, kan vi definere den type svar og en statuskode, vi kan forvente, når en fejl opstår.

Lad os se, hvordan vi ville definere det forventede svar til GET-anmodningen på / foos / {id} ressource, når der ikke findes nogen ressource med det givne id:

 404: body: application / json: type: Fejleksempel: {"meddelelse": "Ikke fundet", "kode": 1001}

3. RAML med JSON-skema

Før datatyper blev introduceret i RAML 1.0, blev objekter, anmodningsorganer og responsorganer defineret ved hjælp af JSON-skema.

Ved brug af datatyper kan være meget kraftfuld, men der er tilfælde, hvor du stadig vil bruge JSON Schema. I RAML 0,8 definerede du dine skemaer ved hjælp af rodniveauet skemaer afsnit.

Det er stadig gyldigt, men det anbefales at bruge typer sektion i stedet siden brugen af skemaer kan blive udfaset i en fremtidig version. Begge typer og skemaer, såvel som type og skema, er synonyme.

Sådan defineres Foo-objekttypen på rodniveauet for .raml fil ved hjælp af JSON-skema:

typer: foo: | {"$ schema": "//json-schema.org/schema", "type": "object", "description": "Foo details", "egenskaber": {"id": {"type": heltal }, "name": {"type": "string"}, "ownerName": {"type": "string"}}, "required": ["id", "name"]}

Og her er hvordan du vil henvise til skemaet i GET / foos / {id} ressource definition:

/ foos: ... / {id}: get: beskrivelse: Få en Foo efter dens id-svar: 200: body: application / json: type: foo ...

4. Refactoring med inkluderer

Som vi kan se fra ovenstående afsnit, bliver vores API temmelig detaljeret og gentagne.

RAML-specifikationen giver en inkluderingsmekanisme, der giver os mulighed for at eksternalisere gentagne og lange sektioner af kode.

Vi kan omformulere vores API-definition ved hjælp af inkluderer, hvilket gør den mere kortfattet og mindre tilbøjelig til at indeholde de typer fejl, der skyldes metoden "kopier / indsæt / rett overalt".

For eksempel kan vi lægge datatypen til en Foo objekt i filen typer / Foo.raml og typen for en Fejl objekt i typer / Error.raml. Så vores typer sektion ville se sådan ud:

typer: Foo:! inkluderer typer / Foo.raml Fejl:! inkluderer typer / Error.raml

Og hvis vi bruger JSON-skema i stedet, vores typer sektion kan se sådan ud:

typer: foo:! inkluderer skemaer / foo.json fejl:! inkluderer skemaer / error.json

5. Afslutning af API

Efter at have eksternaliseret alle datatyper og eksempler til deres filer, kan vi omlægge vores API ved hjælp af inkluderingsfaciliteten:

#% RAML 1.0 titel: Baeldung Foo REST Services API-version: v1-protokoller: [HTTPS] baseUri: //rest-api.baeldung.com/api/{version} mediaType: application / json secureBy: basicAuth securitySchemes: basicAuth: beskrivelse: Hver anmodning skal indeholde de overskrifter, der er nødvendige for grundlæggende godkendelsestype: Grundlæggende godkendelse beskrevet af: overskrifter: Autorisation: beskrivelse: Bruges til at sende Base64-kodet "brugernavn: adgangskode" legitimationsoplysninger type: strengrespons: 401: beskrivelse: | Uberettiget. Enten er det angivne kombination af brugernavn og adgangskode ugyldigt, eller brugeren har ikke adgang til det indhold, der leveres af den anmodede URL. typer: Foo:! inkluderer typer / Foo.raml Fejl:! inkluderer typer / Error.raml / foos: get: beskrivelse: Liste over alle Foos matchende forespørgselskriterier, hvis de findes; Ellers anfør alle Foos-forespørgslerParametre: navn ?: streng ejernavn ?: strengrespons: 200: body: application / json: type: Foo [] eksempel:! inkluderer eksempler / Foos.json post: beskrivelse: Opret en ny Foo body: applikation / json: type: Foo eksempel:! inkluderer eksempler / Foo.json svar: 201: body: applikation / json: type: Foo eksempel:! inkluderer eksempler / Foo.json / {id}: get: beskrivelse: Få en Foo efter id svar: 200: body: application / json: type: Foo eksempel:! inkluderer eksempler / Foo.json 404: body: application / json: type: Error eksempel:! include eksempler / Error.json put: beskrivelse: Opdater en Foo ved id body: application / json: type: Foo eksempel:! inkluderer eksempler / Foo.json svar: 200: body: application / json: type: Foo eksempel:! include eksempler / Foo.json 404: body: application / json: type : Fejleksempel:! Inkluderer eksempler / Error.json sletning: beskrivelse: Slet en Foo ved id-svar: 204: 404: body: application / json: type: Fejleksempel:! Inkluder eksempler / Error.json / name / {name} : get: beskrivelse: Liste over alle Foos med et bestemt navnesvar: 200: body: application / json: type: Foo [] eksempel:! Inkluderer eksempler / Foos.json

6. RAML-værktøjer

En af de store ting ved RAML er værktøjsstøtten.

Der er værktøjer til parsing, validering og redigering af RAML API'er; værktøjer til generering af klientkoder; værktøjer til generering af API-dokumentation i HTML- og PDF-formater; og værktøjer, der hjælper os med at teste mod en RAML API-specifikation.

Der er endda et værktøj, der konverterer en Swagger JSON API til RAML.

Her er et udsnit af tilgængelige værktøjer:

  • API Designer - et webbaseret værktøj rettet mod hurtigt og effektivt API-design
  • API Workbench - en IDE til design, bygning, test og dokumentation af RESTful API'er, der understøtter både RAML 0.8 og 1.0
  • RAML Cop - et værktøj til validering af RAML-filer
  • RAML til JAX-RS - et sæt værktøjer til at generere et skelet af Java + JAX-RS-applikationskode fra en RAML-spec eller til at generere en RAML-spec fra en eksisterende JAX-RS-applikation
  • RAML Sublime Plugin - et syntaks-highlighter-plugin til Sublime teksteditor
  • RAML til HTML - et værktøj til generering af HTML-dokumentation fra RAML
  • raml2pdf - et værktøj til generering af PDF-dokumentation fra RAML
  • RAML2Wiki - et værktøj til at generere Wiki-dokumentation (ved hjælp af Confluence / JIRA markup)
  • SoapUI RAML Plugin - et RAML-plugin til den populære SoapUI funktionelle API-testpakke
  • Vigia - en integrationstestsuite, der er i stand til at generere testsager baseret på en RAML-definition

For en komplet liste over RAML-værktøjer og relaterede projekter, besøg RAML-projekter-siden.

7. RAML's nuværende tilstand

RAML 1.0 (RC) -specifikationen fik status som frigivelseskandidat den 3. november 2015, og på tidspunktet for denne skrivning forventedes version 1.0 at blive afsluttet inden for en måned.

Dens forgænger, RAML 0.8, blev oprindeligt frigivet i efteråret 2014 og understøttes stadig af et utal af værktøjer.

8. Yderligere læsning

Her er nogle links, som vi kan finde nyttige under vores rejse med RAML.

  • RAML.org - det officielle sted for RAML-specifikationen
  • json-schema.org - hjemmet til JSON-skemaet
  • Forståelse af JSON-skema
  • JSON Schema Generator
  • Wikipedia RAML-side

9. Konklusion

Denne artikel introducerede RESTful API Modelling Language (RAML). Vi demonstrerede nogle grundlæggende syntaks til at skrive en simpel API-specifikation ved hjælp af RAML 1.0 (RC) spec.

Og vi så måder at gøre vores definitioner mere koncise ved hjælp af syntaktiske genveje og eksternaliserende eksempler, datatyper og skemaer til 'inkludere' filer.

Derefter introducerede vi en samling af kraftfulde værktøjer, der arbejder med RAML-specifikationen for at hjælpe med hverdagslige API-design, udvikling, test og dokumentationsopgaver.

Med den kommende officielle udgivelse af version 1.0 af specifikationen kombineret med den overvældende støtte fra værktøjsudviklere ser det ud til, at RAML er kommet for at blive.

Næste » Fjern afskedigelser i RAML med ressourcetyper og træk

Populære Indlæg

Seneste indlæg

Copyright da.streamalism.org 2024
$config[zx-auto] not found$config[zx-overlay] not found