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

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?

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.

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

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.