Avaliação da Usabilidade da API – Entrevista

Esta página reúne os registro da entrevista realizadas com desenvolvedores de software (alunos de qualidade de software), como parte da avaliação de usabilidade da API AgroMart. Os participantes foram convidados a explorar a documentação da API, simular uma requisição simples e refletir sobre mensagens de erro e retorno da API.

Participantes Entrevistados

Participante	Matricula	Nível de experiencia	Data da entrevista
Mayara Alves	200025058	Intermediário	08/07/2025
Philipe Barbosa	211062830	Intermediário	08/07/2025
Felipe Pedroza	231026330	Básico	08/07/2025
Felipe Souto	190087188	Básico	08/07/2025
Vinícius Mendes	211063265	Intermediário	08/07/2025

Entrevista

O vídeo da entrevista esta disponivel no link abaixo:

Vídeo da Entrevista da avaliação

Resultados Quantitativos

Parte 1

1.1 Você entendeu facilmente o propósito geral da API?
( Sim / Mais ou menos / Não )

Mayara Alves: Mais ou menos

Philipe Barbosa: Mais ou menos

Felipe Pedroza: Mais ou menos

Felipe Souto: Mais ou menos

Vinícius Mendes: Mais ou menos

1.2 Em uma escala de 1 a 5, como você avalia a clareza geral da documentação?
( 1 = Muito ruim / 5 = Muito clara )

Mayara Alves: 2

Philipe Barbosa: 1

Felipe Pedroza: 2

Felipe Souto: 2

Vinícius Mendes: 2

1.3 A estrutura da documentação (títulos, agrupamento, ordem dos endpoints) facilitou a navegação?
( Sim / Parcialmente / Não )

Mayara Alves: Mais ou menos

Philipe Barbosa: Não

Felipe Pedroza: Não

Felipe Souto: Mais ou menos

Vinícius Mendes: Mais ou menos

1.4 Foi fácil encontrar o endpoint necessário para executar uma ação simples (ex: buscar produtos)?
( Sim / Mais ou menos / Não )

Mayara Alves: Não

Philipe Barbosa: Mais ou menos

Felipe Pedroza: Mais ou menos

Felipe Souto: Mais ou menos

Vinícius Mendes: Sim

1.5 Quanto tempo você estima que levaria para montar e testar uma requisição básica (ex: GET de produtos)?
( Tempo estimado: ___ minutos )

Mayara Alves: 5-8 minutos

Philipe Barbosa: 30 minutos

Felipe Pedroza: 20 minutos

Felipe Souto: depende do usuário

Vinícius Mendes: 5 minutos

1.6 Que melhorias você sugeriria na documentação?

Mayara Alves: A documentação poderia ser mais completa, contemplando todos os passos ate a criação de cada funcionalidade.

Philipe Barbosa: Criar uma documentação, clara e concisa. De fácil acesso, e de forma documentada passo a passo.

Felipe Pedroza: Maior clareza, passo a passo exato de tudo que é necessario ter na docuementação

Felipe Souto: Colocar mais detalhes na documentação para saber como funciona corretamente.

Vinícius Mendes: Cobrir mais a parte de tecnologias são necessárias para executar o projeto, um guia melhor de exeução e explicação dos componentes do projeto.

Parte 2

2.1 A API retorna mensagens de erro compreensíveis?
( Sim / Parcialmente / Não )

Mayara Alves: Não

Philipe Barbosa: Parcialmente

Felipe Pedroza: Sim

Felipe Souto: Parcialmente

Vinícius Mendes: Não

2.2 Em uma escala de 1 a 5, como você avalia a clareza das mensagens de erro da API?
( Nota: ___ )

Mayara Alves: 1

Philipe Barbosa: 2

Felipe Pedroza: 4

Felipe Souto: 4

Vinícius Mendes: 3

2.3 Você se sentiria confiante em resolver o problema com base apenas na mensagem retornada?
( Sim / Talvez / Não )

Mayara Alves: Não

Philipe Barbosa: Sim

Felipe Pedroza: Talvez

Felipe Souto: Talvez

Vinícius Mendes: Não

2.4 O retorno dos endpoints que você consultou era padronizado, estruturado e fácil de ler?
( Sim / Parcialmente / Não )

Mayara Alves: Parcialmente

Philipe Barbosa: Não

Felipe Pedroza: Parcialmente

Felipe Souto: Parcialmente

Vinícius Mendes: Sim

2.5 De forma geral, como você classificaria a experiência de integração com essa API?
( Muito difícil / Difícil / Regular / Fácil / Muito fácil )

Mayara Alves: Muito difícil

Philipe Barbosa: Muito difícil

Felipe Pedroza: Difícil

Felipe Souto: Difícil

Vinícius Mendes: Difícil

Comentários Qualitativos de melhorias

Mayara Alves: Se fosse totalmente documentado, as versões e os erros.

Philipe Barbosa: O uso claro de um arquivo de exemplo para as variáveis de ambiente.

Felipe Pedroza: Documentação clara

Felipe Souto: Se tivesse um passo a passo

Vinícius Mendes: Ter uma documentação boa, para evitar os erros simples

Grafico das respostas (Google forms)

Parte 1

1.1 Você entendeu facilmente o propósito geral da API?

Figura 1: Questão 1.1

Fonte: Google forms

1.2 Em uma escala de 1 a 5, como você avalia a clareza geral da documentação?

Figura 2: Questão 1.2

Fonte: Google forms

1.3 A estrutura da documentação (títulos, agrupamento, ordem dos endpoints) facilitou a navegação?

Figura 3: Questão 1.3

Fonte: Google forms

1.4 Foi fácil encontrar o endpoint necessário para executar uma ação simples (ex: buscar produtos)?

Figura 4: Questão 1.4

Fonte: Google forms

1.5 Quanto tempo você estima que levaria para montar e testar uma requisição básica (ex: GET de produtos)?

Figura 5: Questão 1.5

Fonte: Google forms

1.6 Que melhorias você sugeriria na documentação?

Figura 6: Questão 1.6

Fonte: Google forms

Parte 2

2.1 A API retorna mensagens de erro compreensíveis?

Figura 7: Questão 2.1

Fonte: Google forms

2.2 Em uma escala de 1 a 5, como você avalia a clareza das mensagens de erro da API?

Figura 8: Questão 2.2

Fonte: Google forms

2.3 Você se sentiria confiante em resolver o problema com base apenas na mensagem retornada?

Figura 9: Questão 2.3

Fonte: Google forms

2.4 O retorno dos endpoints que você consultou era padronizado, estruturado e fácil de ler?

Figura 10: Questão 2.4

Fonte: Google forms

2.5 De forma geral, como você classificaria a experiência de integração com essa API?

Figura 11: Questão 2.5

Fonte: Google forms

Considerações Finais

Com base nas respostas coletadas durante a entrevista, é possível concluir que a usabilidade da API AgroMart apresenta sérias limitações que impactam negativamente a experiência de integração. A maioria dos entrevistados relatou dificuldades para compreender o propósito da API, navegar pela documentação e encontrar os endpoints necessários. As notas atribuídas à clareza da documentação foram majoritariamente baixas, com destaque para a ausência de um passo a passo estruturado, exemplos práticos e informações sobre tecnologias envolvidas.

Além disso, as mensagens de erro retornadas pela API foram consideradas pouco claras por boa parte dos participantes, o que compromete a autonomia dos desenvolvedores na resolução de problemas. Apesar de alguns reconhecerem uma estrutura minimamente padronizada nas respostas da API, a avaliação geral foi de que a integração é difícil ou muito difícil, especialmente para usuários com menor experiência.

Diante desses resultados, torna-se evidente a necessidade de reestruturar a documentação da API, adotando boas práticas de usabilidade, como a inclusão de exemplos práticos, explicações detalhadas sobre configuração do ambiente, descrição clara dos endpoints e padronização das mensagens de erro. Investir na melhoria da documentação e na experiência do desenvolvedor é essencial para garantir a efetiva adoção da API e o sucesso do projeto como um todo.

📑 Histórico de Versão

Versão	Data	Descrição	Autor
1.0	08/07/2025	Criação da página do roteiro da entrevista	Mayara Alves