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.

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.

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.

#%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

(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 de número.

date Value MUST be a string representation of a date as defined in RFC2616 Section 3.3 [RFC2616]. See Date

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 subconjunto do tipo

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

(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.