Existe algum padrão para descrições legíveis por máquina de serviços RESTful?

5

Interajai com algumas APIs RESTful que forneceram documentação excelente para humanos e URIs descritivos, mas nenhuma delas parece retornar descrições legíveis por máquina de si mesmas.

Não é muito difícil escrever métodos próprios que montam os caminhos certos, e muitas bibliotecas de API específicas de idioma já são apenas invólucros em torno de solicitações RESTful. Mas o próximo nível de abstração parece realmente útil: uma biblioteca que pode ler na própria documentação legível por uma máquina da API e gerar automaticamente os invólucros, talvez com uma chamada para algum URI padrão como base_url + '/documentation'

Existe algum padrão para documentação de API legível por máquina? Estou fazendo o REST errado? Eu sou um programador relativamente novo, mas parece uma boa ideia.

    
por ecmendenhall 18.09.2012 / 03:27
fonte

1 resposta

2

Sim, existem várias maneiras que você pode usar.

Um deles é gerar seu código de cliente, testes e documentação usando um conjunto de ferramentas que suportam WADL. Alguns exemplos podem ser encontrados nesta postagem do blog .

Você também pode achar melhor usar o WADL, em vez do WSDL 2.0, porque ele é menos detalhado e simplificado (IMHO). De fato, usando o WADL, você descreve exatamente o que o usuário vê na página de documentação, usando apenas a sintaxe WADL XML. E também é uma das razões pelas quais é tão fácil escrever geradores de documentação baseados em XSLT para WADL.

    
por 18.09.2012 / 04:02
fonte