RAML (software) - RAML (software)

RAML
Filnavn udvidelse
.raml
Internetmedietype
ansøgning/raml+yaml
Udviklet af RAML -arbejdsgruppe
Seneste udgivelse
1.0
(16. maj 2016 ) ( 2016-05-16 )
Forlænget fra YAML
Standard github .com /raml-org /raml-spec /blob /master /versioner /raml-10 /raml-10 .md /
Internet side raml .org

RESTful API Modeling Language ( RAML ) er et YAML -baseret sprog til beskrivelse af RESTful API'er . Det giver alle de oplysninger, der er nødvendige for at beskrive RESTful eller praktisk talt RESTful API'er. Selvom designet med RESTful API'er i tankerne, er RAML i stand til at beskrive API'er, der ikke overholder alle begrænsninger ved REST (deraf beskrivelsen "praktisk talt RESTful"). Det tilskynder til genbrug, muliggør opdagelse og mønsterdeling og sigter mod fortjenstbaseret fremkomst af bedste praksis.

Historie

RAML blev først foreslået i 2013. Den første RAML -specifikation blev forfattet af Uri Sarid, Emiliano Lesende, Santiago Vacas og Damian Martinez, og opnåede støtte fra teknologiledere som MuleSoft, AngularJS, Intuit, Box, PayPal, Programmerbar Web og API Web Science, Kin Lane, SOA Software og Cisco. Udviklingen styres af RAML Workgroup. De nuværende arbejdsgruppesignatører omfatter teknologiledere fra MuleSoft (Uri Sarid, CTO), AngularJS (Misko Hevery, projektstifter), Intuit (Ivan Lazarov, Chief Enterprise Architect), Airware (Peter Rexer, Director of Product - Developer Platform), Programmerbar Web og API Science (John Musser, grundlægger), SOA Software (Tony Gullotta, udviklingsdirektør), Cisco (Jaideep Subedar, Senior Manager, Product Management - Application Integration Solutions Group), VMware (Kevin Duffey, Senior MTS Engineer), Akamai Technologies (Rob Daigneau, arkitektdirektør for Akamai's OPEN API Platform) og Restlet (Jerome Louvel, CTO og grundlægger). RAML er et varemærke tilhørende MuleSoft.

Meget få eksisterende API'er opfylder de præcise kriterier for at blive klassificeret som RESTful API'er. Som de fleste API -initiativer i 2010'erne har RAML derfor i første omgang fokuseret på det grundlæggende i praktisk RESTful API'er, herunder ressourcer, metoder, parametre og responsorganer, der ikke behøver at være hypermedier. Der er planer om at bevæge sig mod mere strengt RESTful API'er efterhånden som teknologiens udvikling og markedet tillader det.

Der er en række grunde til, at RAML er brudt ud af at være et proprietært leverandørsprog og har vist sig interessant for det bredere API -fællesskab:

  • RAML har været open-sourced sammen med værktøjer og parsere til fælles sprog. Udviklingen af ​​RAML vil blive overvåget af en styregruppe af API- og UX-praktikere, og der er et voksende økosystem af tredjepartsværktøjer, der udvikles omkring RAML
  • MuleSoft begyndte oprindeligt at bruge Swagger (nu OpenAPI Specification ), men besluttede, at det var bedst egnet til at dokumentere en eksisterende API, ikke til at designe en API fra bunden. RAML udviklede sig ud fra behovet for at understøtte up-front API-design i et kortfattet, menneskecentrisk sprog
  • API -beskrivelser er ofte omfattende og gentagne, hvilket kan gøre dem vanskelige at forstå og bruge og langsom vedtagelse af API'erne. RAML har introduceret sprogfunktioner, der understøtter strukturerede filer og arv, der adresserer tværgående bekymringer

En ny organisation, under sponsorering af Linux Foundation , kaldet Open API Initiative blev oprettet i 2015 for at standardisere beskrivelsen af RESTful API'er. En række virksomheder, herunder SmartBear , Google , IBM og Microsoft, var stiftende medlemmer. SmartBear donerede Swagger -specifikationen til den nye gruppe. RAML og API Blueprint er også under overvejelse af gruppen.

Eksempel

Dette er et eksempel på en RAML -fil. Som med YAML viser indrykning indlejring. 

  #%RAML 0.8

  title: World Music API
  baseUri: http://example.api.com/{version}
  version: v1
  traits:
    - paged:
        queryParameters:
          pages:
            description: The number of pages to return
            type: number
    - secured: !include http://raml-example.com/secured.yml
  /songs:
    is: [ paged, secured ]
    get:
      queryParameters:
        genre:
          description: filter the songs by genre
    post:
    /{songId}:
      get:
        responses:
          200:
            body:
              application/json:
                schema: |
                  { "$schema": "http://json-schema.org/schema",
                    "type": "object",
                    "description": "A canonical song",
                    "properties": {
                      "title":  { "type": "string" },
                      "artist": { "type": "string" }
                    },
                    "required": [ "title", "artist" ]
                  }
              application/xml:
      delete:
        description: |
          This method will *delete* an **individual song**

Nogle højdepunkter:

  • linje 7, 12: definerer træk, der påberåbes flere steder
  • linje 12: en Inkluder fil
  • linje 13, 14: definer en "ressource" datatype "/sange"; bruger tidligere definerede træk
  • linje 15, 19, 37: definerer HTTP -metoder
  • linje 25, 36: MIME -typer .

API -gateways, der understøtter RAML

Desuden kan du konvertere din RAML -specifikation til enten OpenAPI eller API Blueprint ved hjælp af APIMATIC , så du kan bruge yderligere API -gateways.

Se også

Alternative RESTful -modelleringssprog

Noter

Referencer

eksterne links