RAML (mjukvara)

RAML
Filnamnstillägg	.raml
Internet mediatyp	applikation/raml+yaml
Utvecklad av	RAML arbetsgrupp
Senaste släppningen	; 1.0 16 maj 2016
Förlängt från	YAML
Standard	github .com /raml-org /raml-spec /blob / master /versions /raml-10 /raml-10 .md /
Hemsida	raml .org

RESTful API Modeling Language ( RAML ) är ett YAML -baserat språk för att beskriva statiska API:er (men inte REST API:er). Den tillhandahåller all information som behövs för att beskriva API:er på nivå 2 i Richardson Maturity Model . Även om den är designad med RESTful API:er i åtanke, kan RAML inte beskriva API:er som inte följer alla restriktioner för REST. Det uppmuntrar till återanvändning, möjliggör upptäckt och mönsterdelning och syftar till meritbaserad framväxt av bästa praxis.

Historia

RAML föreslogs först 2013. Den ursprungliga RAML-specifikationen skrevs av Uri Sarid, Emiliano Lesende, Santiago Vacas och Damian Martinez, och fick stöd från teknikledare som MuleSoft, AngularJS, Intuit, Box, PayPal, Programmerbar webb och API Web Science, Kin Lane, SOA Software och Cisco. Utvecklingen hanteras av RAML Workgroup. De nuvarande arbetsgruppens undertecknare inkluderar teknikledare från MuleSoft (Uri Sarid, CTO), AngularJS (Misko Hevery, projektgrundare), Intuit (Ivan Lazarov, Chief Enterprise Architect), Airware (Peter Rexer, Director of Product - Developer Platform), Programmerbar webb och API Science (John Musser, grundare), SOA Software (Tony Gullotta, utvecklingsdirektör), Cisco (Jaideep Subedar, Senior Manager, Product Management - Application Integration Solutions Group), VMware (Kevin Duffey, Senior MTS Engineer), Akamai Technologies (Rob Daigneau, arkitekturchef för Akamais OPEN API-plattform) och Restlet (Jerome Louvel, CTO och grundare). RAML är ett varumärke som tillhör MuleSoft.

Mycket få befintliga API:er uppfyller de exakta kriterierna för att klassificeras som RESTful API:er. Följaktligen, som de flesta API-initiativ under 2010-talet, har RAML initialt fokuserat på grunderna i API:er inklusive resurser, metoder, parametrar och svarsorgan som inte behöver vara hypermedia. Det finns planer på att gå mot mer strikt RESTful API:er allteftersom teknikutvecklingen och marknaden tillåter. ^{[ citat behövs ]}

Det finns ett antal anledningar till att RAML har brutit ut från att vara ett proprietärt leverantörsspråk och har visat sig intressant för den bredare API-gemenskapen:

RAML har varit öppen källkod tillsammans med verktyg och tolkar för vanliga språk. Utvecklingen av RAML kommer att övervakas av en styrgrupp bestående av API- och UX-utövare, och det finns ett framväxande ekosystem av tredjepartsverktyg som utvecklas runt RAML
MuleSoft började ursprungligen använda Swagger (nu OpenAPI Specification ), men beslutade att det var bäst lämpat för att dokumentera ett befintligt API, inte för att designa ett API från början. RAML utvecklades ur behovet av att stödja up-front API-design i ett kortfattat, människocentrerat språk
API-beskrivningar är ofta utförliga och repetitiva, vilket kan göra dem svåra att förstå och använda, och långsam adoption av API:erna. RAML har introducerat språkfunktioner som stöder strukturerade filer och arv som tar itu med övergripande problem

En ny organisation, under sponsring av Linux Foundation , kallad Open API Initiative inrättades 2015 för att standardisera beskrivningen av HTTP API:er. Ett antal företag inklusive SmartBear , Google , IBM och Microsoft var grundande medlemmar. SmartBear donerade Swagger-specifikationen till den nya gruppen. RAML och API Blueprint är också under övervägande av gruppen.

Exempel

Detta är ett exempel på en RAML-fil. Precis som med YAML visar indrag häckning.

  

   
   
   
  
     
        
          
             
             
       
  
        
    
      
        
           
    
    
      
        
          
            
              
                 
                  
                    
                    
                    
                      
                      
                    
                    
                  
              
      
         
           #%RAML 0.8  title  :  World Music API  baseUri  :  http://example.api.com/{version}  version  :  v1  egenskaper  :  -  paged  :  queryParameters  :  pages  :  description  :  Antalet sidor att returnera  typ  :  nummer  -  säker  :  !inkludera  http://raml-example.com/secured.yml  /låtar  :  är  :  [  sökt  ,  säkrad  ]  get  :  queryParameters  :  genre  :  description  :  filtrera låtarna efter genrepost  :  /  {songId}  :  get  :  responses  :  200  :  body  :  application/json  :  schema  :  |  { "$schema": "http://json-schema.org/schema",  "type": "object",  "description": "En kanonisk låt",  "properties": {  "title": { "type ": "string" },  "artist": { "type": "sträng" }  },  "required": [ "titel", "artist" ]  }  application/xml  :  delete  :  description  :  |  Den här metoden kommer att *ta bort* en **enskild låt**

Några höjdpunkter:

rad 7, 12: definierar egenskaper som åberopas på flera ställen
rad 12: en Inkludera-fil
rad 13, 14: definiera en "resurs" datatyp "/låtar"; använder tidigare definierade egenskaper
rad 15, 19, 37: definierar HTTP- metoder
rad 25, 36: MIME-typer .

API-gateways som stöder RAML

Apigee
MuleSoft
AWS API Gateway av AWS (genom AWS API Gateway Importer )
Akana
Restlet

Dessutom kan du konvertera din RAML-specifikation till antingen OpenAPI eller API Blueprint med APIMATIC , vilket gör att du kan använda ytterligare API-gateways.

Se även

Alternativa HTTP API-modelleringsspråk

Anteckningar

externa länkar