Como testar permissões em uma API de arquivos: recursos, ações e casos negativos

Um guia para planejar, não o contrato de uma API

Autenticação e autorização respondem a perguntas diferentes. Autenticação diz respeito a quem apresenta uma solicitação; autorização, a se essa identidade pode realizar uma ação. Essa distinção ajuda a organizar uma revisão, mas não indica, por si só, quais permissões, recursos ou respostas uma API de arquivos específica aceita.

Por isso, trate os exemplos deste guia como ideias de planejamento, não como comportamentos verificados de um serviço. Antes de preparar casos, consulte a documentação primária e a configuração aplicável. É lá que você deve procurar as operações disponíveis, os requisitos de autenticação e os critérios que permitem determinar qual resultado é esperado. Não deduza rotas, funções, propriedade de arquivos nem códigos de resposta por analogia com outras APIs.

As referências a produtos específicos também não são regras universais. A Microsoft documenta o ApiCenterMinimalPermissionsPlugin como uma ferramenta para verificar se um aplicativo chama APIs com permissões mínimas ([Microsoft Learn](https://learn.microsoft.com/es-es/microsoft-cloud/dev/dev-proxy/how-to/check-minimal-api-permissions)). No caso do Google Drive, a documentação informa que as permissões necessárias ao aplicativo devem ser declaradas na configuração de consentimento do OAuth ([Google for Developers](https://developers.google.com/workspace/drive/api/guides/api-specific-auth?hl=es-419)). Nenhuma dessas referências define como outra API funciona.

• Separe as ideias gerais de teste das capacidades confirmadas para o serviço que você está integrando.
• Use a documentação do produto e a configuração vigente para definir os resultados esperados.
• Não transfira para outra API as permissões, ferramentas ou fluxos da Microsoft ou do Google.

Defina o escopo antes de preparar os casos

Comece delimitando o que você quer validar. Anote quais identidades de teste estão autorizadas, quais recursos de ensaio estão disponíveis e quais operações aparecem na documentação. O objetivo não é preencher uma matriz hipotética, mas transformar requisitos verificáveis em perguntas de teste concretas.

Para cada operação que você realmente pretende avaliar, registre as pré-condições relevantes e a fonte do critério esperado: por exemplo, uma seção da documentação ou uma configuração do serviço. Se ainda não consegue explicar por que uma identidade deveria poder realizar a ação, marque o critério como pendente, em vez de apresentá-lo como um fato.

Não presuma que o serviço define um arquivo como «próprio» nem que organiza o acesso por funções, grupos ou links. Se esses conceitos estiverem documentados, use as definições exatas. Se não estiverem, evite inventá-los para preencher o plano. Descrever com precisão o que não se sabe é mais útil do que criar uma regra presumida.

• Registre a identidade lógica de teste, o recurso, a ação e suas pré-condições.
• Associe cada resultado esperado a uma fonte verificável.
• Deixe explícitos os pontos que a documentação não esclarece, sem transformá-los em requisitos.

Crie casos que respondam a perguntas concretas

Um planejamento útil associa cada caso a uma pergunta específica: qual requisito está sendo verificado? Qual condição é mantida? Que resultado permitiria confirmar ou refutar o critério? Essa estrutura ajuda a diferenciar um teste informativo de uma solicitação que apenas produz uma resposta sem contexto.

Quando o contrato da API descrever operações diferentes, avalie-as separadamente. Um resultado observado para uma operação não demonstra automaticamente o que aconteceria com outra. Da mesma forma, não classifique um caso como permitido ou negado sem uma base documentada para essa expectativa.

Se quiser comparar duas condições, altere uma única variável quando o projeto da API e o ambiente permitirem. Assim, será mais fácil atribuir qualquer diferença observada. Esta é uma recomendação geral de planejamento; não pressupõe que a API use uma estrutura específica nem que aceite todos os ensaios.

Mantenha os resultados esperados e os observados separados. Se a API responder de uma forma que a documentação não prevê, registre a diferença e a fonte consultada. Não transforme automaticamente uma resposta específica em critério de aprovação ou reprovação quando o contrato não especificar esse comportamento.

• Formule uma pergunta verificável para cada caso.
• Diferencie operações e condições, em vez de extrapolar um resultado para toda a API.
• Registre qualquer ambiguidade do contrato como uma questão em aberto.

Exemplo condicionado: testar com outro identificador

Se a documentação descrever solicitações que identificam recursos e o ambiente permitir testá-las, você pode propor um ensaio controlado com outro recurso de teste. A pergunta seria se o resultado observado corresponde ao critério estabelecido pela documentação e pela configuração. Este exemplo não afirma que todas as APIs usem identificadores nem que compartilhem o mesmo comportamento de autorização.

Antes de executar o ensaio, confirme que você tem autorização e que os recursos são adequados para testes. Defina previamente quais informações precisa observar e evite fazer alterações que não façam parte do caso. Se a operação puder modificar conteúdo, verifique depois o estado do recurso usando um método permitido pelo serviço e registre apenas as evidências necessárias.

Não use um identificador de terceiros nem dados privados no lugar de um ambiente de teste. Também não interprete uma resposta genérica como prova de uma política específica se o contrato não permitir essa conclusão. Quando o comportamento esperado não estiver descrito, o resultado adequado do trabalho pode ser documentar a dúvida e pedir esclarecimentos.

• Realize o ensaio somente com credenciais e recursos autorizados.
• Use identificadores de teste apenas se a API e o ambiente permitirem esse tipo de verificação.
• Compare o que foi observado com o critério documentado, não com uma suposição.

Documente resultados que outra pessoa possa revisar

Um registro claro permite entender o que foi verificado sem depender da memória de quem executou o teste. Para cada caso, guarde a data, a identidade lógica de teste, o recurso de ensaio, a ação, as pré-condições e os resultados esperados e observados. Inclua a referência documental que justifica o critério.

Se guardar solicitações, respostas ou capturas de tela, revise o conteúdo antes de compartilhá-lo. Oculte credenciais, tokens e outros segredos, e evite incluir informações privadas desnecessárias para explicar o resultado. Quando o corpo de uma resposta não for necessário, guarde uma descrição ou um trecho editado em vez de copiá-lo por inteiro.

Separe fatos observados de interpretações. Por exemplo, registre qual resposta foi recebida e, em outro campo, se ela corresponde ao que o contrato descreve. Se a documentação não esclarecer uma diferença, anote-a como questão pendente e encaminhe-a ao fornecedor ou responsável técnico.

• Inclua o critério e sua fonte junto ao resultado de cada caso.
• Oculte segredos e limite as evidências ao necessário para a revisão.
• Diferencie observações, conclusões e questões ainda não resolvidas.

Relacione a revisão às capacidades da Apification

O catálogo da Apification informa que o Cloud permite proteger arquivos e serviços com permissões, OTP, autenticação externa, restrições e janelas de publicação. Também descreve o compartilhamento por links, usuários ou grupos. Essas capacidades ajudam a identificar temas que podem ser relevantes ao revisar uma configuração do Cloud, mas não especificam, por si só, um modelo de autorização para uma API nem o resultado de uma solicitação específica.

O catálogo também informa que o Cloud e seus serviços podem ser integrados por API REST, OpenAPI, webhooks, iframe e JavaScript. Essa descrição confirma opções de integração no nível do produto, mas não fornece aqui endpoints, parâmetros ou respostas esperadas. Para implementá-las ou criar testes para um serviço específico, consulte a documentação aplicável.

Mantenha essa separação nas suas conclusões: você pode descrever as capacidades confirmadas pelo catálogo e, em separado, apontar quais detalhes de autorização não estão especificados nas informações disponíveis. Assim, você evita prometer compatibilidade ou comportamentos que ainda precisam ser verificados.

• Use o catálogo para identificar capacidades do produto, não para deduzir detalhes de endpoints.
• Consulte a documentação específica antes de transformar uma capacidade em um caso de integração.
• Deixe claro qualquer detalhe de autorização que ainda não tenha sido verificado.

Finalize a revisão com uma lista de verificação

Antes de integrar ou compartilhar os resultados, verifique se o escopo está claro para outra pessoa e se os critérios têm respaldo. Se um teste não puder ser executado com autorização ou não tiver um resultado esperado justificável, não o apresente como uma verificação conclusiva.

A lista a seguir serve como controle editorial do plano. Ela não substitui a documentação do serviço, não garante um resultado de segurança e não define respostas comuns a todas as APIs. Seu objetivo é ajudar a identificar suposições e evidências incompletas antes de tomar decisões de integração.

• Cada operação avaliada está descrita para a API específica?
• Os resultados esperados se baseiam em documentação ou configuração verificável?
• Os resultados observados estão diferenciados das conclusões?
• Os testes estão limitados a recursos e credenciais autorizados?
• Segredos e dados privados foram removidos das evidências?
• As dúvidas pendentes foram identificadas, em vez de resolvidas por suposições?

Perguntas frequentes