Documentando uma interface REST com um fluxograma

Alguém tem sugestões para criar uma representação de fluxograma de uma interface da web no estilo REST? No interesse de fornecer documentação completa para os co-desenvolvedores, eu tenho trabalhado na modelagem da interface para modificar e gerar um recurso do produto:

Esse sistema em particular começa a agir de maneira diferente com a autenticação de usuário / contagem de recursos; portanto, antes de fazer modificações, estou procurando esclarecimentos:

Complexidade: como você simplificaria a estrutura geral para facilitar a leitura?
Símbolo de exibição: isso é apropriado para representar uma página?
Símbolo de operação manual: isso é apropriado para representar uma ação do usuário como um clique no botão?

Qualquer outra sugestão seria muito apreciada.

Minhas desculpas pelo re-post. O site principal do stackexchange sugeriu que essa pergunta era melhor apresentada aos programadores.

documentation rest flowchart

— James Kassemi
fonte

Respostas:

Eu sinto que o diagrama de sequência / gráfico de sequência de mensagens é mais adequado para documentar a interação da API RESTful. O que você tem é um diagrama de estado, enquanto a API RESTful, por definição, é sem estado.

insira a descrição da imagem aqui

— vartec
fonte

O servidor em uma arquitetura RESTful é sem estado, no entanto, o próprio sistema não é. O estado é armazenado no cliente e as possíveis transições de estado são codificadas na representação de um recurso para que o cliente possa iniciar a transição para um novo estado fazendo uma solicitação ao servidor. Eu acho que um diagrama de estados é bastante eficaz na comunicação do estado geral do sistema, mesmo que não documente com precisão as solicitações e respostas entre os componentes do cliente e do servidor.

— Adam Jaskiewicz

@ Adam: você está certo sobre o sistema em geral. Mas a pergunta pergunta explicitamente sobre a documentação da interface REST, não o sistema inteiro.

— vartec 28/07/11

Obrigado, vartec, o MSC documenta efetivamente a interface REST nesta instância. Ainda estou curioso para ouvir melhorias na documentação deste modelo do estado do cliente.

— James Kassemi

Os sistemas RESTful que implementam a restrição de hipertexto fazem com que o cliente atue como uma máquina de estado. Eu descobri que o uso de diagramas de tipo de máquina de estado é uma ferramenta muito mais eficaz para documentar as interações cliente / servidor RESTful.

— Darrel Miller

Existe possível descrever if-s e while-s neste diagrama?

— Hellboy

Definitivamente, acho que uma máquina de estado é o caminho certo para documentar essas interações de um sistema RESTful. No entanto, ainda estou trabalhando no caminho certo para representar os fatores hipermídia no diagrama. Aqui estão alguns diagramas experimentais que eu fiz.

Labirinto

insira a descrição da imagem aqui

— Darrel Miller
fonte

Meus dois centavos sobre o assunto, pois estou trabalhando com isso no momento:

foco em recursos e suas relações
- e não na ação e, portanto, o método HTTP
- quando você segue um link, não importa se você fez um GET ou POST, seus próximos estados possíveis são ditados principalmente pelo recurso atual e muito menos pelo método HTTP da solicitação

Com aquilo em mente:

remova alguns links óbvios (ou seja, para si próprio, para fazer root)
remova o rótulo das relações se apenas indicar "este [carro] tem um [proprietário]", onde o recurso de origem é carro e o recurso de destino é proprietário. Não adiciona nada
um gráfico interativo pode ser de grande ajuda com um diagrama de estados complexo ( exemplo )

— Andrei Neculau
fonte