Este artigo apresenta os conceitos centrais no Apidog, uma ferramenta API-first projetada para design, teste e colaboração eficientes de APIs. Muitos conceitos diferem de produtos semelhantes, como Postman. Entendê-los ajudará você a navegar pelo fluxo de trabalho do Apidog de forma eficaz.Projeto#
Um Projeto no Apidog é a unidade principal de colaboração, contendo módulos, ambientes, cenários de teste e muito mais. Ele serve como um contêiner para todo o trabalho relacionado a APIs dentro de uma equipe.Componentes principais de um projeto#
Módulos: Agrupamentos lógicos de endpoints e componentes relacionados.
Ambientes: Conjuntos de variáveis para diferentes estágios de implantação (por exemplo, desenvolvimento, staging, produção).
Cenários de teste: Coleções de requisições para testes automatizados.
Especificações de endpoints: Documentação de API baseada nos padrões OpenAPI/Swagger.
Comparação com Postman#
| Conceito do Apidog | Equivalente no Postman | Descrição |
|---|
| Projeto | Workspace | Unidade organizacional de nível superior para colaboração. |
| Módulo | Pasta de coleção | Agrupa endpoints relacionados. |
| Equipe | Equipe | Recursos de acesso compartilhado e colaboração. |
Projetos permitem colaboração contínua, possibilitando que vários usuários trabalhem em APIs simultaneamente, mantendo controle de versão e permissões de acesso.
Módulo#
Um Módulo organiza endpoints logicamente dentro de um projeto, semelhante a um "serviço" em uma arquitetura de microsserviços. Cada módulo representa um arquivo de especificação OpenAPI independente.Recursos de um módulo#
Contém endpoints, schemas, respostas e esquemas de segurança relacionados.
Configurado com uma Base URL por ambiente para geração automática de URL.
Oferece suporte a operações de importação/exportação no nível do módulo para melhor conformidade com padrões.
Quando usar módulos#
Para microsserviços: cada serviço como um módulo separado.
Para várias APIs: agrupe endpoints por funcionalidade ou domínio.
Padrão: novos projetos começam com um módulo; adicione mais conforme necessário para várias URLs base.
Módulos se alinham à OpenAPI Specification (OAS), facilitando a integração com outras ferramentas e mantendo limites de API bem definidos.
Endpoint#
Um Endpoint é o elemento central na abordagem API-first do Apidog, representando uma operação de API específica (por exemplo, GET /users/{id}).Gerenciamento de endpoints#
Agrupados em estruturas de diretórios para organização.
Vinculado a casos de endpoint para exemplos de requisição salvos.
Diferenças em relação ao Postman#
| Aspecto | Apidog (baseado em endpoint) | Postman (baseado em requisição) |
|---|
| Unidade básica | Endpoint (especificação de API) | Requisição (chamada individual) |
| Alterações na especificação | Atualiza casos e testes automaticamente | Reescrita manual necessária |
| Estrutura | Extensão OAS com depuração | Especificações e requisições separadas |
No Apidog, alterações nas especificações de endpoint são propagadas automaticamente para todos os casos dependentes, reduzindo a sobrecarga de manutenção por meio dessa abordagem orientada por especificação.
Ambiente#
Um Ambiente gerencia variáveis e URLs base para diferentes contextos de implantação, permitindo alternância contínua entre dev, staging e produção.Principais recursos#
Contém variáveis de ambiente para valores dinâmicos.
Oferece suporte a várias URLs base por ambiente para microsserviços. Construção automática de URL: URL base + caminho do endpoint.
Exemplo de URL base#
Suponha um projeto com três serviços:| Serviço | URL base (Prod) | Caminho do endpoint | URL completa |
|---|
| Usuário | https://user.example.com | GET /user/{id} | https://user.example.com/user/{id} |
| Pedido | https://order.example.com | GET /order/{id} | https://order.example.com/order/{id} |
| Produto | https://product.example.com | GET /product/{id} | https://product.example.com/product/{id} |
Não há necessidade de placeholders manuais {{BaseUrl}}; o Apidog detecta o módulo e aplica automaticamente a URL base correta.
Requisição#
Uma Requisição é uma chamada de API independente, não vinculada a especificações de endpoint, semelhante às requisições do Postman.Capacidades de requisição#
Crie independentemente das especificações. Analise requisições bem-sucedidas em especificações de endpoint. Use para testes ad hoc ou APIs não documentadas.
Requisições oferecem flexibilidade para cenários em que as especificações de API não estão predefinidas, preenchendo a lacuna entre fluxos de trabalho design-first e request-first.
Cenário de teste#
Um Cenário de teste executa lotes de requisições, semelhante às coleções do Postman, com recursos avançados de automação.Recursos#
Capacidades avançadas#
Relatórios de teste e testes de desempenho.
Testes orientados por dados.
Cenários de teste são sincronizados automaticamente com alterações na especificação da API, garantindo que os testes permaneçam válidos à medida que as APIs evoluem.
Modo Design-first e modo Request-first#
O módulo de APIs do Apidog possui dois modos que podem ser alternados no canto inferior esquerdo da interface: Design-first Mode e Request-first Mode.Ambos os modos oferecem funcionalidades semelhantes, mas com interfaces diferentes, atendendo a diferentes fluxos de trabalho de equipe.Modo Design-first#
Recomendado para equipes que praticam API-design first.
Defina especificações de API antes do desenvolvimento e dos testes.
Ideal para projetos planejados e orientados por especificação.
Modo Request-first#
Adequado para equipes que se concentram primeiro no desenvolvimento de backend.
Crie requisições e, em seguida, gere especificações a partir de chamadas bem-sucedidas.
Perfeito para APIs não documentadas ou integrações de terceiros.
Resumo#
Entender estes conceitos centrais ajudará você a aproveitar a abordagem API-first do Apidog para design, teste e colaboração eficientes. Comece criando um projeto, organize endpoints em módulos, defina ambientes para diferentes estágios e crie cenários de teste para automação.Para leitura adicional, explore as páginas de documentação vinculadas ou experimente a interface do Apidog para ver estes conceitos em ação.
Pronto para começar?#
Começar do zero
Comece a usar o Apidog do zeroMigrar para o Apidog
Comece migrando para o Apidog 