Estruturação de documentação online para uma API REST

85

Estou construindo minha primeira API Rest que serializa dados para os formatos JSON e XML. Eu gostaria de fornecer uma página de índice para clientes de API, onde eles seriam capazes de escolher endpoints implementados.

Quais informações eu preciso incluir para tornar minha API mais útil e como devo organizá-la?

api rest indexing Aumanets
fonte

Respostas:

6

Essa é uma pergunta muito complexa para uma resposta simples.

Você pode querer dar uma olhada nas estruturas de API existentes, como Swagger Specification ( OpenAPI ), e serviços como apiary.io e apiblueprint.org .

Além disso, aqui está um exemplo da mesma API REST descrita, organizada e até estilizada de três maneiras diferentes. Pode ser um bom começo para você aprender com os métodos comuns existentes.

No nível mais alto, acho que os documentos da API REST de qualidade exigem pelo menos o seguinte:

  • uma lista de todos os seus endpoints de API (URLs básicos / relativos)
  • tipo de método HTTP GET / POST / ... correspondente para cada endpoint
  • solicitação / resposta do tipo MIME (como codificar parâmetros e analisar respostas)
  • um exemplo de solicitação / resposta, incluindo cabeçalhos HTTP
  • tipo e formato especificado para todos os parâmetros, incluindo aqueles no URL, corpo e cabeçalhos
  • uma breve descrição do texto e notas importantes
  • um pequeno snippet de código mostrando o uso do endpoint em linguagens de programação da web populares

Além disso, há muitos frameworks de documentos baseados em JSON / XML que podem analisar sua definição de API ou esquema e gerar um conjunto conveniente de documentos para você. Mas a escolha de um sistema de geração de documentos depende do seu projeto, linguagem, ambiente de desenvolvimento e muitas outras coisas.

Igor Kroitor
fonte