Como documentar os requisitos para uma API sistematicamente?

Atualmente, estou trabalhando em um projeto, no qual tenho que analisar os requisitos de dois sistemas de TI, que usam computação em nuvem, para uma API em nuvem. Em outras palavras, tenho que analisar quais requisitos esses sistemas têm para uma API de nuvem, para que eles possam trocá-la, enquanto conseguem atingir seus objetivos atuais.

Deixe-me dar um exemplo para alguns requisitos informais do Projeto A:

1. Ao iniciar máquinas virtuais na nuvem por meio da API, deve ser possível especificar o tamanho da memória, tipo de CPU, sistema operacional e uma chave SSH para o usuário raiz.
2. Deve ser possível monitorar o tráfego da rede de entrada e saída por hora por máquina virtual.
3. A API deve suportar a atribuição de IPs públicos a uma máquina virtual e a recuperação dos IPs públicos.
4. ...

Em uma fase posterior do projeto, analisarei alguns padrões de computação em nuvem que padronizam as APIs da nuvem para descobrir onde estão as possíveis falhas nos padrões atuais. Uma descoberta poderia e provavelmente será que um determinado padrão não suporta o monitoramento do uso de recursos e, portanto, atualmente não é utilizável.

Atualmente, estou tentando encontrar uma maneira de anotar e classificar sistematicamente meus requisitos. Eu sinto que a maneira como eu as escrevo atualmente (como os três pontos acima) é muito informal.

Li alguns livros de engenharia de requisitos e arquitetura de software, mas todos eles se concentram demais nos detalhes e na implementação. Realmente me importo apenas com as funcionalidades fornecidas pela API / interface e não acho que os diagramas UML etc. sejam a escolha certa para mim. Acho que atualmente os requisitos que coletei podem ser descritos como histórias de usuários, mas isso já é suficiente para uma análise sofisticada de requisitos? Provavelmente eu deveria ir "um nível mais fundo" ...

Leia Documentando arquiteturas de software, segunda edição: Views and Beyond , capítulo 7: Documentando interfaces de software.

Ou, pelo menos, verifique algumas documentações conhecidas da API, como a Amazon ( Google Maps , GData - desatualizada, mas complexa) da Amazon ( S3 ) ou inspecione a documentação dos aplicativos e serviços da Microsoft, reunidos no MSDN (para serviços Live , mas mesmo para Windows )

Normalmente, uma documentação da API possui 3 partes:

• uma visão geral sobre o que é a coisa, o que alguém poderia fazer com isso, talvez uma visão geral da arquitetura
• Um guia do desenvolvedor, explicando algumas tarefas comuns com a API, geralmente com exemplos de código e aplicativos de exemplo para download.
• Uma referência de API de como deve funcionar

Em teoria - se acreditarmos no Mythical Man Month de Brook - você projeta a documentação e garante que haja uma implementação correspondente.

Agora de volta à prática

Os requisitos de design para uma API funcionam como qualquer design de software.

1. Você inscreve os diferentes atores que devem usar a API (usando um diagrama de contexto, por exemplo)
2. Você detalha as necessidades típicas de cada ator do sistema com casos de uso
3. Para cada caso de uso, você desenvolve um conjunto de cenários sobre como o sistema imaginado seria usado (o livro Escrevendo casos de uso eficazes pode ajudá-lo nisso)
4. Você cria diagramas de robustez , diagramas de seqüência ou diagramas de atividades , mas projeta o comportamento com base nos cenários para determinar quais mensagens precisam ser passadas
5. A partir das mensagens, você deduz a arquitetura de dados subjacente , observando quais parâmetros são necessários para que cada mensagem seja comunicada com êxito.

Muitas pessoas começariam com a estrutura de dados subjacente, mas acho que isso é bobagem: computadores (e objetos, por sinal) são sobre interações. Você precisa entender o que precisa ser comunicado de ambos os lados para executar uma interação bem-sucedida. Os dados são apenas o parâmetro dessas interações.

Normalmente, faço diagramas de atividades ou fluxogramas simples que mostram os argumentos passados ​​como objetos ou classes. Ou seja, há um fluxo de controle em andamento, mas vemos quais informações uma das partes passou para a outra.

Depois de terminar tudo isso, você pega seus cenários novamente e começa a criar testes de aceitação . Isso ocorre porque as APIs devem ser usadas pelos clientes de computador; portanto, seu primeiro código deve ser um cliente de computador que realiza a recuperação automática como teste.

Os testes de aceitação são escritos no formulário "entrada fornecida" - "saída esperada" ou como código. Você pode encontrar muitos livros sobre BDD e TDD que explicarão como escrever bons testes.

Além disso, por aqui, você começa a publicar livros sobre interfaces REST e similares, caso esteja criando uma API da Web, pois seus testes precisam ser executáveis desde o primeiro dia.

A partir dos cenários, você também cria código de exemplo e guia do desenvolvedor.

Nos diagramas de sequência e na arquitetura de dados, você desenvolve a referência da API.

Adicione uma pitada de HTML, verifique se todos os testes foram aprovados e se o seu aplicativo é rápido, seguro e robusto o suficiente, e vamos sair com ele!

(Eu sei, isso era uma cachoeira: o ágil é o mesmo, exceto que você sempre faz apenas uma pequena parte disso, por exemplo, alguns cenários por sprint)

Você realmente não precisa ser mais "formal" do que o que tem. Você está escrevendo para os humanos lerem e provavelmente principalmente para si mesmo, então lembre-se disso. Minha única sugestão é colocá-lo em uma hierarquia e numerá-lo em formato de estrutura de tópicos. Dessa forma, em revisões, listas de verificação e outras coisas, você pode se referir a um número como o 3.0.1 como uma abreviação e facilmente desambiguar o que está falando.