Introduksjon til RAML - RESTful API Modeling Language

Denne artikkelen er en del av en serie: • Introduksjon til RAML - The RESTful API Modeling Language (nåværende artikkel) • Eliminer redundanser i RAML med ressurstyper og egenskaper

• Modulært RAML som bruker inkluderer, biblioteker, overlegg og utvidelser

• Definer egendefinerte RAML-egenskaper ved hjelp av merknader

1. Oversikt

I denne artikkelen introduserer vi RESTful API Modelling Language (RAML), et leverandør-nøytralt, åpent spesifikasjonsspråk bygget på YAML 1.2 og JSON for å beskrive RESTful APIer.

Vi vil dekke grunnleggende RAML 1.0-syntaks og filstruktur når vi demonstrerer hvordan du definerer en enkel JSON-basert API. Vi viser også hvordan du forenkler vedlikehold av RAML-filer ved bruk av inkluderer. Og hvis du har eldre API-er som bruker JSON-skjema, viser vi hvordan du kan innlemme skjemaer i RAML.

Deretter introduserer vi en håndfull verktøy som kan forbedre reisen din til RAML, inkludert redigeringsverktøy, dokumentasjonsgeneratorer og andre.

Til slutt vil vi avslutte med å beskrive den nåværende tilstanden til RAML-spesifikasjonen.

2. Definere API-en din (Opprette .raml fil)

API-en vi definerer er ganske enkel: gitt enhetstyper Foo, definere grunnleggende CRUD-operasjoner og et par spørringsoperasjoner. Her er ressursene vi vil definere for API: et:

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

Og la oss definere API-en vår til å være statsløs, ved hjelp av HTTP Basic-autentisering, og som skal leveres kryptert over HTTPS. Til slutt, la oss velge JSON for vårt datatransportformat (XML støttes også).

2.1. Innstillinger på rotnivå

Vi begynner med å lage en enkel tekstfil med navnet api.raml (de .raml prefiks anbefales; navnet er vilkårlig) og legg til RAML-versjonsoverskriften på linje en. På rotnivået til filen definerer vi innstillinger som gjelder for hele API:

#% RAML 1.0 tittel: Baeldung Foo REST Services API ved hjelp av datatyperversjon: v1-protokoller: [HTTPS] baseUri: //myapi.mysite.com/api/{version} mediaType: application / json

Legg merke til på linje 3 bruken av seler {} rundt ordet “versjon“. Slik forteller vi RAML at “versjon" refererer til en eiendom og skal utvides. Derfor den faktiske baseUri vil være: //myapi.mysite.com/v1

[Merk: versjon eiendommen er valgfri og trenger ikke være en del av baseUri.]

2.2. Sikkerhet

Sikkerhet er også definert på rotnivået til .raml fil. Så la oss legge til vår definisjon av grunnleggende HTTP-sikkerhetsskjema:

securitySchemes: basicAuth: beskrivelse: Hver forespørsel må inneholde overskriftene som er nødvendige for grunnleggende godkjenningstype: Basic Authentication beskrevet av By: headers: Authorization: description: Brukes til å sende Base64-kodet "brukernavn: passord" legitimasjonstype: strengrespons: 401: beskrivelse: | Uautorisert. Enten er det oppgitte brukernavnet og passordkombinasjonen ugyldig, eller så får ikke brukeren tilgang til innholdet fra den forespurte URL-en.

2.3. Datatyper

Deretter definerer vi datatypene som API-en vår vil bruke:

typer: Foo: type: objektegenskaper: id: obligatorisk: sann type: heltall navn: obligatorisk: sann type: streng eier Navn: nødvendig: falsk type: streng

Ovennevnte eksempel bruker utvidet syntaks for å definere datatypene våre. RAML gir noen syntaktiske snarveier for å gjøre typedefinisjonene våre mindre detaljerte. Her er tilsvarende datatyper som bruker disse snarveiene:

typer: Foo: egenskaper: id: heltall navn: streng eiernavn ?: streng Feil: egenskaper: kode: heltall melding: streng

'?' tegn etter et eiendomsnavn erklærer at eiendommen ikke er nødvendig.

2.4. Ressurser

Nå vil vi definere toppnivåressursen (URI) for API-en vår:

/ foos:

2.5. URI-parametere

Deretter utvider vi listen over ressurser, basert på vår ressurs på toppnivå:

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

Her definerer klammeparentesene {} rundt eiendomsnavn URI-parametere. De representerer plassholdere i hver URI og refererer ikke til rotnivå RAML-filegenskaper som vi så ovenfor i baseUri erklæring. De tilførte linjene representerer ressursene / foos / {id} og / foos / name / {name}.

2.6. Metoder

Neste trinn er å definere HTTP-metodene som gjelder for hver ressurs:

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

2.7. Spørsmålsparametere

Nå definerer vi en måte å spørre på foos samling ved hjelp av søkeparametere. Merk at spørringsparametere er definert med samme syntaks som vi brukte ovenfor for datatyper:

/ foos: get: beskrivelse: Liste opp alle Foos som samsvarer med søkekriteriene, hvis de er gitt; Ellers viser du alle Foos queryParameters: navn ?: streng eiernavn ?: streng

2.8. Svar

Nå som vi har definert alle ressursene for API-en vår, inkludert URI-parametere, HTTP-metoder og spørringsparametere, er det på tide å definere forventede svar og statuskoder. Svarformater defineres vanligvis angående datatyper og eksempler.

JSON-skjema kan brukes i stedet for datatyper for bakoverkompatibilitet med en tidligere versjon av RAML. Vi introduserer JSON-skjema i avsnitt 3.

[Merk: I kodebitene nedenfor indikerer en linje som bare inneholder tre prikker (...) at noen linjer hoppes over for kortfattet.]

La oss starte med den enkle GET-operasjonen på / foos / {id}:

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

Dette eksemplet viser at ved å utføre en GET-forespørsel på ressursen / foos / {id}, vi burde få tilbake matchingen Foo i form av et JSON-objekt og en HTTP-statuskode på 200.

Slik definerer vi GET-forespørselen på / foos ressurs:

/ foos: get: beskrivelse: Liste opp alle Foos som samsvarer med søkekriteriene, hvis de er gitt; ellers liste opp alle Foos queryParameters: navn ?: streng eiernavn ?: streng svar: 200: body: application / json: type: Foo [] eksempel: | [{"id": 1, "name": "First Foo"}, {"id": 2, "name": "Second Foo"}]

Legg merke til bruken av firkantede parenteser [] vedlagt Foo type. Dette demonstrerer hvordan vi vil definere et responsorgan som inneholder en rekke Foo objekter, med eksemplet en rekke JSON-objekter.

2.9. Forespørsel

Deretter definerer vi forespørselsorganene som tilsvarer hver POST- og PUT-forespørsel. La oss begynne med å lage en ny Foo gjenstand:

/ foos: ... post: beskrivelse: Opprett en ny Foo-kropp: applikasjon / json: type: Foo-eksempel: {"id": 5, "name": "En annen foo"} svar: 201: body: application / json : type: Foo eksempel: {"id": 5, "name": "Another foo"}

2.10. Statuskoder

Legg merke til i eksemplet ovenfor at når vi oppretter et nytt objekt, returnerer vi en HTTP-status på 201. PUT-operasjonen for oppdatering av et objekt vil returnere en HTTP-status på 200, ved å bruke de samme forespørsels- og svarorganene som POST-operasjonen.

I tillegg til forventede svar og statuskoder som vi returnerer når en forespørsel er vellykket, kan vi definere typen svar og en statuskode som kan forventes når en feil oppstår.

La oss se hvordan vi vil definere det forventede svaret for GET-forespørselen på / foos / {id} ressurs når ingen ressurs blir funnet med den angitte id:

 404: body: application / json: type: Feileksempel: {"message": "Ikke funnet", "code": 1001}

3. RAML Med JSON-skjema

Før datatyper ble introdusert i RAML 1.0, objekter, forespørselsorganer og responsorganer ble definert ved hjelp av JSON Schema.

Ved hjelp av datatyper kan være veldig kraftig, men det er tilfeller der du fortsatt vil bruke JSON Schema. I RAML 0,8 definerte du skjemaene dine ved hjelp av rotnivået skjemaer seksjon.

Det er fortsatt gyldig, men det anbefales å bruke typer seksjon i stedet siden bruk av skjemaer kan avvikles i en fremtidig versjon. Både typer og skjemaer, i tillegg til type og skjema, er synonyme.

Slik definerer du Foo-objekttypen på rotnivået til .raml fil ved hjelp av JSON-skjema:

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

Og her er hvordan du vil referere til skjemaet i GET / foos / {id} ressursdefinisjon:

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

4. Refactoring med inkluderer

Som vi kan se fra avsnittene ovenfor, blir API-en vår ganske ordentlig og repeterende.

RAML-spesifikasjonen gir en inkluderingsmekanisme som lar oss eksternalisere gjentatte og lange kodeseksjoner.

Vi kan omformulere API-definisjonen vår ved hjelp av inkluderer, noe som gjør den mer kortfattet og mindre sannsynlig å inneholde typene feil som skyldes "kopier / lim inn / fikse overalt" -metoden.

For eksempel kan vi sette datatypen for en Foo objekt i filen typer / Foo.raml og typen for en Feil objekt i typer / Error.raml. Så vår typer seksjonen vil se slik ut:

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

Og hvis vi bruker JSON-skjema i stedet, vår typer delen kan se slik ut:

typer: foo:! inkluderer skjemaer / foo.json feil:! inkluderer skjemaer / error.json

5. Fullføre API

Etter å ha eksternalisert alle datatypene og eksemplene til filene deres, kan vi omformulere API-en vår ved hjelp av inkluderer-anlegget:

#% RAML 1.0 tittel: Baeldung Foo REST Services API versjon: v1-protokoller: [HTTPS] baseUri: //rest-api.baeldung.com/api/{version} mediaType: applikasjon / json sikretBy: basicAuth securitySchemes: basicAuth: beskrivelse: Hver forespørsel må inneholde overskriftene som er nødvendige for grunnleggende godkjenningstype: Grunnleggende godkjenning beskrevet Av: overskrifter: Autorisasjon: beskrivelse: Brukes til å sende Base64-kodet "brukernavn: passord" legitimasjonstype: strengrespons: 401: beskrivelse: | Uautorisert. Enten er det oppgitte brukernavnet og passordkombinasjonen ugyldig, eller så får ikke brukeren tilgang til innholdet fra den forespurte URL-en. typer: Foo:! inkluderer typer / Foo.raml Feil:! inkluderer typer / Error.raml / foos: get: beskrivelse: Liste opp alle Foos som samsvarer med søkekriterier, hvis gitt; ellers liste opp alle Foos queryParameters: navn ?: streng eiernavn ?: streng svar: 200: body: application / json: type: Foo [] eksempel:! inkluderer eksempler / Foos.json post: beskrivelse: Opprett et nytt Foo body: application / json: type: Foo eksempel:! inkluderer eksempler / Foo.json svar: 201: body: applikasjon / json: type: Foo eksempel:! inkluderer eksempler / Foo.json / {id}: get: beskrivelse: Få en Foo etter id svar: 200: body: application / json: type: Foo eksempel:! inkluderer eksempler / Foo.json 404: body: application / json: type: Error eksempel:! inkluderer eksempler / Error.json put: beskrivelse: Oppdater en Foo med id body: application / json: type: Foo eksempel:! inkluderer eksempler / Foo.json svar: 200: body: application / json: type: Foo eksempel:! inkluderer eksempler / Foo.json 404: body: application / json: type : Feileksempel:! Inkluderer eksempler / Error.json delete: beskrivelse: Slett en Foo etter id-svar: 204: 404: body: application / json: type: Error example:! Include examples / Error.json / name / {name} : få: beskrivelse: Liste alle Foos med et bestemt navn svar: 200: body: application / json: type: Foo [] eksempel:! Inkluderer eksempler / Foos.json

6. RAML Verktøy

En av de gode tingene med RAML er verktøystøtten.

Det finnes verktøy for parsing, validering og redigering av RAML APIer; verktøy for generering av klientkoder; verktøy for å generere API-dokumentasjon i HTML- og PDF-formater; og verktøy som hjelper oss med testing mot en RAML API-spesifikasjon.

Det er til og med et verktøy som vil konvertere en Swagger JSON API til RAML.

Her er et utvalg av tilgjengelige verktøy:

  • API Designer - et nettbasert verktøy rettet mot rask og effektiv API-design
  • API Workbench - en IDE for å designe, bygge, teste og dokumentere RESTful APIer som støtter både RAML 0.8 og 1.0
  • RAML Cop - et verktøy for validering av RAML-filer
  • RAML for JAX-RS - et sett med verktøy for å generere et skjelett av Java + JAX-RS-applikasjonskode fra en RAML-spesifikasjon, eller for å generere en RAML-spesifikasjon fra en eksisterende JAX-RS-applikasjon
  • RAML Sublime Plugin - et syntaks-highlighter-plugin for Sublime teksteditor
  • RAML til HTML - et verktøy for å generere HTML-dokumentasjon fra RAML
  • raml2pdf - et verktøy for å generere PDF-dokumentasjon fra RAML
  • RAML2Wiki - et verktøy for å generere Wiki-dokumentasjon (ved hjelp av Confluence / JIRA markup)
  • SoapUI RAML Plugin - et RAML-plugin for den populære SoapUI funksjonelle API-testpakken
  • Vigia - en integrasjonstestpakke som kan generere testsaker basert på en RAML-definisjon

For en komplett liste over RAML-verktøy og relaterte prosjekter, besøk RAML-prosjekt-siden.

7. Den nåværende tilstanden til RAML

RAML 1.0 (RC) -spesifikasjonen fikk status som utgiverkandidat 3. november 2015, og i skrivende stund forventes versjon 1.0 å være ferdig innen måneden.

Forgjengeren, RAML 0.8, ble opprinnelig utgitt høsten 2014 og støttes fortsatt av et mylder av verktøy.

8. Videre lesing

Her er noen lenker som vi kan finne nyttige under vår reise med RAML.

  • RAML.org - det offisielle nettstedet til RAML-spesifikasjonen
  • json-schema.org - hjemmet til JSON-skjemaet
  • Forståelse av JSON-skjema
  • JSON Schema Generator
  • Wikipedia RAML-side

9. Konklusjon

Denne artikkelen introduserte RESTful API Modelling Language (RAML). Vi demonstrerte noen grunnleggende syntakser for å skrive en enkel API-spesifikasjon ved bruk av RAML 1.0 (RC) -spesifikasjonen.

Og vi så måter å gjøre definisjonene våre mer konsise ved å bruke syntaktiske snarveier og eksterne eksempler, datatyper og skjemaer til å inkludere filer.

Deretter introduserte vi en samling kraftige verktøy som fungerer med RAML-spesifikasjonen for å hjelpe til med hverdagslige API-design, utvikling, testing og dokumentasjonsoppgaver.

Med den kommende offisielle utgivelsen av versjon 1.0 av spesifikasjonen, kombinert med den overveldende støtten fra verktøyutviklere, ser det ut til at RAML er kommet for å bli.

Neste » Eliminer oppsigelser i RAML med ressurstyper og egenskaper

Populære Innlegg

Siste innlegg

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