O documento descreve a RAML (Representational State Transfer API Modeling Language), uma linguagem baseada em YAML para descrever APIs RESTful. Ele fornece detalhes sobre como a RAML especifica recursos, métodos, parâmetros e inclusão de arquivos para definir APIs RESTful de forma concisa e extensível.

1. RAML™ Versão 0.8: RESTful API Modeling Language – Parte 1
Abstract
Raml ™ é uma linguagem baseada em YAML que descreve APIs RESTful. Juntamente
com a especificação YAML, esta especificação fornece todas as informações necessárias
para descrever APIs RESTful; para criar API client-código e geradores de código do
servidor API; e criar a documentação do usuário API de definições de API Raml.
Introdução
Esta especificação descreve Raml. Raml é uma descrição do processo-capazes legível e
máquina de uma interface API RESTful. geradores de API de documentação, geradores
API client-código e servidores da API consomem um documento Raml para criar
documentação do usuário, o código do cliente, e topos de código do servidor,
respectivamente.
Convenções
As palavras chave "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", e "OPTIONAL" na presente
documento devem ser interpretados como descrito no RFC 2119 RFC2119.
Overview
Raml define o tipo de mídia "application / Raml + yaml" para descrever e documentar
os recursos de uma API RESTful, tais como métodos e esquema dos recursos. Raml é
baseado em YAML e documentos Raml apoiar todos os YAML 1,2 características. A
extensão de arquivo recomendado para arquivos Raml é ".raml".
Raml também oferece facilidades para extensivamente documentar uma API RESTful,
possibilitando ferramentas de gerador de documentação para extrair a documentação
do usuário e traduzi-lo para formatos visuais, como PDF, HTML, e assim por diante.
Raml também introduz o conceito inovador de tipos de recursos e características para a
caracterização de recursos e métodos, minimizando assim a quantidade de repetição
necessária para especificar projeto de uma API RESTful.
Esta especificação RAML é organizada como abaixo:
 Basic Information. Explica como descrever aspectos fundamentais de uma API
RESTful, como seu nome, título e localização.

2.  User Documentation. Descreve como incluir a documentação de suporte para
a API RESTful.
 Resource Types and Traits. . Descreve o mecanismo opcional para usar tipos
de recursos Raml e traços para caracterizar os recursos de modo a evitar a
repetição desnecessária na definição da API RESTful.
 Resources. Descreve como especificar os recursos de uma API RESTful,
métodos e esquema de 'recursos, e as interações entre recursos.
Terminology
Para esta especificação, a definição de API será utilizada para designar a descrição de
uma API usando esta especificação e Raml especificação refere-se ao documento atual.
REST
REST é usado no contexto de uma API implementado usando os princípios de descanso. O
acrônimo REST significa Representational State Transfer e foi introduzido e definida em
2000 por Roy Fielding em sua tese de doutorado [REST] em primeiro lugar.
Resource
Um recurso é o mapeamento conceitual para uma entidade ou conjunto de entidades.
Markup Language
Esta especificação utiliza YAML 1.2 [YAML] como seu formato de núcleo. YAML é um
formato de dados legível que alinha bem com os objetivos do projeto desta
especificação.
definições API Raml são documentos YAML-compliant que começam com uma linha
YAML-comment exigia que indica a versão Raml, como segue:
#%RAML 0.8
A versão Raml deve ser a primeira linha do documento Raml. analisadores Raml deve
interpretar todas as outras linhas comentou-YAML como comentários.
Em Raml, as estruturas de dados YAML são reforçadas para incluir tipos de dados que
não são suportados nativamente. Todos os analisadores de documentos Raml deve
apoiar essas extensões.
Em Raml, todos os valores devem ser interpretados de forma maiúsculas e minúsculas.

3. Includes
A especificação YAML não exige que parsers YAML usar qualquer mecanismo particular
para dividir um arquivo YAML em pedaços menores gerenciáveis. No entanto, os
documentos Raml deve ser capaz de ser dividido entre vários arquivos. Para suportar
esta função, todos os analisadores Raml deve apoiar a inclusão tag, que permite
inclusive Raml e YAML e arquivos de texto regulares.
Neste exemplo, o conteúdo de MyTextFile.txt está incluída como o valor da
propriedade externa.
#%RAML 0.8
external: !include myTextFile.txt
Quando os arquivos Raml ou YAML estão incluídos, analisadores Raml deve não apenas
ler o conteúdo, mas analisá-lo e adicionar o conteúdo para a estrutura declarando
como se o conteúdo foram declarados em linha.
Para simplificar a definição API, e porque o contexto de análise do arquivo incluído não
é compartilhada entre o arquivo incluído e seu pai, um arquivo incluído não deve usar
uma referência YAML a uma âncora em um arquivo separado. Da mesma forma, uma
referência feita a partir de um arquivo-mãe não deve fazer referência a uma âncora
estrutura definida em um arquivo incluído.
Neste exemplo, o ficheiro properties.raml define duas propriedades. O arquivo big.raml
inclui o arquivo properties.raml.
#%RAML 0.8
#properties.raml
propertyA: valueA
propertyB: valueB
#%RAML 0.8
#big.raml
external: !include properties.raml
A estrutura resultante é equivalente a declaração abaixo:
#%RAML 0.8
external:
propertyA: valueA
propertyB: valueB
Se um caminho relativo é usado para o arquivo incluído, o caminho é interpretada em
relação à localização do ficheiro original (inclusive). Se o arquivo original é buscada
como um recurso HTTP, o arquivo incluído deve ser atingida através de HTTP.
No exemplo a seguir, porque o ficheiro original (inclusive) está localizado
em http://example-domain.org/api/example.raml, theproperties.raml arquivo deve ser
obtido a partir http://example-domain.org/api/properties.raml.

4. #%RAML 0.8
#http://example-domain.org/api/example.raml
external: !include properties.raml
Se o arquivo incluído tem um dos seguintes tipos de mídia:
 application/raml+yaml
 text/yaml
 text/x-yaml
 application/yaml
 application/x-yaml
ou um .raml ou .yml ou .yaml extensão, RAML analisadores MUST analisar o conteúdo
do arquivo como conteúdo Raml e anexar as estruturas analisadas para o nó do
documento Raml.
A localização do arquivo a ser incluído, ou seja, o lado direito da! Incluem, deve ser
estático, ou seja, ele não pode conter quaisquer parâmetros de tipo de recurso ou
característica. Isso vai ser reexaminadas para futuras versões do Raml.
Named Parameters
Esta Especificação Raml descreve coleções de parâmetros nomeados para as seguintes
propriedades: URI parâmetros, parâmetros de string de consulta, parâmetros de
formulário, órgãos de solicitação (dependendo do tipo de mídia), e pedido e resposta
cabeçalhos. Todas as coleções especificar atributos dos parâmetros nomeados,
conforme descrito nesta seção.
Alguns parâmetros nomeados são opcionais e outros são necessários. Veja a descrição
de cada parâmetro nomeado.
Salvo disposição em contrário, os valores dos parâmetros nomeados deve ser
formatado como texto simples. Todos os personagens de arquivo YAML válido pode
ser usado em valores de parâmetros nomeados.
displayName
(Opcional) O atributo DisplayName especifica o nome de exibição do parâmetro. É um
nome amigável usado apenas para fins de exibição ou de documentação. Se
displayName não for especificado, o padrão é a chave do imóvel (o nome da
propriedade em si).
description

5. (Opcional) O atributo de descrição descreve o uso a que se destina ou o significado do
parâmetro. Este valor pode ser formatado usando Markdown [markdown].
type
(Opcional) O atributo type especifica o tipo primitivo de valor resolvidos do parâmetro.
clientes API deve retornar / lançar um erro se o valor resolvidos do parâmetro não
coincide com o tipo especificado. Se o tipo não for especificado, o padrão é string. Os
tipos válidos são:
Type Description
string valor deve ser uma string.
number O valor deve ser um número. Indicam números de ponto flutuante, conforme definido pela YAML.
integer O valor deve ser um inteiro. números de ponto flutuante não são permitidos. O tipo inteiro é um subconjunto do tipo
date
Value MUST be a string representation of a date as defined in RFC2616 Section 3.3 [RFC2616]. S
Representations.
boolean Valor deve ser "true" or "false" (sem as aspas).
file
(Aplicavel apenas a Form properties)
O valor deve ser um inteiro. números de ponto flutuante não são permitidos. O tipo inteiro é um
de número..
Date Representations
Tal como definido no [RFC2616], todos os carimbos de data / hora são representados
em Greenwich Mean Time (GMT), que, para efeitos de HTTP é igual a UTC (Tempo
Universal Coordenado). Isto é indicado através da inclusão de "GMT" como a
abreviatura de três letras para o fuso horário. Exemplo: Sun, 06 de novembro de 1994
08:49:37 GMT.
enum

6. (Opcional, aplicável somente para parâmetros do tipo string) O atributo enumeração
fornece uma enumeração de valores válidos do parâmetro. Esta deve ser uma matriz.
Se o atributo enum é definido, os clientes da API e servidores deve verificar se o valor
de um parâmetro corresponde a um valor na matriz enum. Se não houver nenhum
valor correspondente, os clientes e servidores deve tratar isso como um erro.