Conceitos Básicos de Endpoint

No Apidog, projetar e configurar um endpoint de API é uma etapa fundamental para criar APIs robustas e eficazes.

Recomenda-se projetar endpoints em conformidade com a OpenAPI Specification (OAS) para garantir compatibilidade fluida com várias ferramentas e serviços dentro do ecossistema OpenAPI. Desviar da OAS pode levar a problemas de compatibilidade ao utilizar ferramentas e serviços compatíveis com OpenAPI.

Criar um Endpoint

Para criar um novo endpoint no módulo APIs, clique no botão Novo Endpoint.

Um endpoint claro e completo deve incluir os seguintes elementos:

Caminho do endpoint

Método da requisição

Metadados do endpoint

Requisição

Resposta e exemplo

Modo Design-first

Modo Request-first

Modos de Interface

A interface de endpoint do Apidog tem dois modos: Modo Design-first para abordagens API Design-first e Modo Request-first para abordagens Code-first. Você pode alternar os modos no canto inferior esquerdo da interface. Saiba mais sobre Modo Design-first/Modo Request-first.

Caminho do Endpoint

O caminho do endpoint serve como um endereço específico em que a API pode interagir com aplicações externas. É isso que o cliente usará para acessar o serviço de API.

O Apidog segue a abordagem da OpenAPI Specification. Em vez de escrever a URL completa para cada endpoint, você só precisa inserir o caminho (por exemplo, /users). A URL base é definida no ambiente, e o Apidog a adiciona automaticamente ao fazer requisições para o endpoint.

Para manter a consistência com o padrão OpenAPI, o Apidog também recomenda iniciar todos os caminhos com uma /. Isso mantém o design da sua API limpo e organizado, além de garantir que você aproveite todos os benefícios dos recursos do Apidog.

Por Que Iniciar Caminhos com /

Iniciar caminhos com / é recomendado para aderir à OAS. Não iniciar caminhos com / pode levar a vários problemas de compatibilidade ao usar ferramentas dentro do ecossistema OpenAPI.

Além disso, usar / no início dos caminhos permite a utilização da funcionalidade de mock de padrão de URL, essencial para fins de teste e validação no Apidog.

Método da Requisição

O método da requisição determina como o cliente interage com o recurso do lado do servidor. Cada método possui sua própria semântica e dita a resposta do servidor. Ao projetar uma API, selecione o método de requisição mais apropriado com base nos requisitos de negócio para executar efetivamente a operação pretendida.

A seguir estão os métodos de requisição de API comumente usados:

Método	Descrição
GET	Recupera recursos especificados sem efeitos colaterais. Usa parâmetros de consulta para transmitir dados.
POST	Envia dados para processamento e pode ter efeitos colaterais. Os dados geralmente são enviados no corpo da requisição.
PUT	Atualiza ou substitui inteiramente recursos especificados.
DELETE	Remove recursos especificados.
OPTIONS	Consulta os métodos HTTP compatíveis com o recurso de destino.
HEAD	Semelhante a GET, mas recupera apenas os cabeçalhos da resposta. Útil para verificar a existência e modificações de recursos sem baixar o conteúdo do recurso.
PATCH	Atualiza informações parciais de recursos especificados.
TRACE	Retorna a requisição recebida pelo servidor. Usado principalmente para fins de depuração e diagnóstico.
CONNECT	Estabelece um túnel para o servidor, normalmente usado para encaminhamento de requisições de servidor proxy.

Metadados do Endpoint

No Apidog, endpoints vêm com campos de metadados padrão que definem e gerenciam a documentação, a acessibilidade e o ciclo de vida da API.

Aqui está uma visão geral concisa de cada campo de metadados padrão:

Campo	Descrição
Nome	Um nome descritivo que resume a funcionalidade do endpoint.
Status	O status padrão é "Em desenvolvimento". Você pode modificá-lo para refletir diferentes etapas, como Teste ou Produção. Saiba mais sobre status do endpoint.
Mantenedor	Especifica o membro da equipe do Apidog responsável pelo endpoint. Selecione um usuário da sua conta para atribuir essa função.
Tags	Palavras-chave ou frases que categorizam ou descrevem o endpoint. Você pode criar novas tags ou selecionar entre as existentes.
Serviço	A URL base à qual o caminho do endpoint é anexado. Definido por padrão como "Herdar dos pais", mas pode ser especificado manualmente por meio das configurações de ambiente. Saiba mais sobre Ambientes e serviços.
OperationId	Um identificador exclusivo (operationId na OAS) que distingue esta operação dentro da API.
Descrição	Informações detalhadas sobre o propósito e o uso do endpoint, com suporte a Markdown para formatação aprimorada.

Campos Personalizados

Além dos campos de metadados padrão fornecidos para um endpoint, você tem a flexibilidade de adicionar campos personalizados para enriquecer ainda mais os metadados do endpoint.

Requisição

Parâmetros da Requisição

Parâmetros da requisição são opções que podem ser passadas com a requisição para controlar o retorno dos dados ou modificar a resposta do servidor.

Os parâmetros da requisição incluem parâmetros de consulta, parâmetros de caminho, parâmetros de cabeçalho e parâmetros de corpo.

Parâmetros de Consulta

Parâmetros de consulta são pares chave-valor anexados ao final de uma URL após um ponto de interrogação ? e separados por &, da seguinte forma: ?id=2&status=available. Eles são usados para filtrar, classificar ou modificar a saída de um endpoint de API.

INFO

No Apidog, os parâmetros de consulta são descritos em uma seção separada para maior clareza e organização. No entanto, ao enviar uma requisição, esses parâmetros de consulta são concatenados com o caminho do endpoint da maneira descrita acima.

Parâmetros de Caminho

Parâmetros de caminho fazem parte da própria URL do endpoint e são usados para identificar um recurso ou entidade específica dentro da API.

No Apidog, parâmetros de caminho são indicados usando chaves em vez de dois-pontos. Exemplo correto: /pets/{id}, Exemplo incorreto: /pets/:id.

Se você precisar usar variáveis em um parâmetro de caminho, a abordagem recomendada é defini-lo como {parameter} na URL e, então, usar {{variable}} para o valor do parâmetro. Por exemplo:

Recomendado: coloque a variável no valor do parâmetro de caminho

Não recomendado: coloque a variável diretamente na URL

Não Confunda {parameter} e {{variable}}

{parameter}: chaves simples representam parâmetros de caminho no Apidog. Parâmetros de caminho são espaços reservados no caminho da URL que mudam dinamicamente para valores específicos quando o endpoint da API é acessado.

{{variable}}: chaves duplas incluem variáveis dentro das requisições. Essas variáveis podem ser substituídas por valores reais quando a requisição é enviada, permitindo entrada dinâmica e personalizável em interações com a API.

Por Que NÃO Usar {{variable}} no Caminho

Usar {{variable}} não adere à OAS. Seguir a OAS permite integração contínua com diversas ferramentas dentro do ecossistema OpenAPI.

Usar {{variable}} no caminho impedirá o uso da funcionalidade de mock de padrão de URL no Apidog.

Parâmetros de Cabeçalho

Parâmetros de cabeçalho fornecem informações adicionais sobre a requisição que está sendo feita e normalmente são usados para autenticação, tipo de conteúdo e outros metadados.

Saiba Mais

Saiba mais sobre Parâmetros de Cabeçalho.

Parâmetros de Corpo

Parâmetros de corpo contêm os dados a serem enviados no corpo da requisição, normalmente usados em requisições POST, PUT e PATCH para criar ou atualizar um recurso. Os dados geralmente são enviados no formato JSON ou XML.

Saiba Mais

Saiba mais sobre Parâmetros de Corpo.

Descrever Parâmetros

Os parâmetros devem ser descritos com seu nome, tipo (string, integer, boolean etc.), necessidade (obrigatório ou opcional) e quaisquer valores padrão ou restrições.

Ao descrever parâmetros, as seguintes propriedades principais são comumente usadas:

Propriedade	Descrição
Nome	Especifica o nome do parâmetro que está sendo descrito. É um campo obrigatório e deve representar com precisão o parâmetro que está sendo definido.
Tipo	Especifica o tipo de dados do valor do parâmetro. Valores comuns incluem `string`, `number`, `integer`, `boolean`, `array`, `object` e mais. Esta propriedade ajuda a definir o formato e a estrutura do valor do parâmetro.
Descrição	Fornece uma breve explicação ou documentação sobre o parâmetro. Ajuda os usuários a entender o propósito e o uso do parâmetro.
Obrigatório	Especifica se o parâmetro é obrigatório para a requisição da API. É um valor booleano (`true` ou `false`) que indica se o parâmetro deve ser incluído na requisição.
Configurações Avançadas	Define o tipo de dados, o formato e as restrições do parâmetro. Permite que você forneça informações detalhadas sobre a estrutura e o conteúdo esperados do valor do parâmetro.

Editor de Tipo

Você pode modificar com eficiência as configurações avançadas dos parâmetros usando o Editor de Tipo. Saiba mais sobre o Editor de Tipo.

Schemas

Quando o tipo de parâmetro de corpo é JSON ou XML, a estrutura de dados precisa ser definida. A estrutura de dados pode referenciar os schemas.

Saiba Mais

Para obter informações detalhadas sobre schemas, consulte Schemas.

Resposta e Exemplo

Após enviar uma requisição para a API, o servidor retorna uma resposta. Definir as respostas esperadas e fornecer exemplos ilustrativos são etapas cruciais que aprimoram a compreensibilidade e a usabilidade para desenvolvedores que interagem com sua API.

A definição da resposta retornada inclui principalmente as seguintes partes:

Componente	Descrição
Código de Status HTTP	Determine todos os possíveis status de resposta que seu endpoint pode retornar, incluindo respostas padrão como 200 (OK), 404 (Not Found) ou 500 (Server Error).
Formato de Dados	Defina o formato da resposta que a API retornará para cada código de status. Isso pode estar em `JSON`, `XML`, `HTML`, `Raw`, `Binary` ou qualquer outro formato adequado.
Schema	Para respostas que transportam dados (principalmente status 200), detalhe a estrutura do payload da resposta. Isso inclui especificar tipos, objetos aninhados, campos opcionais e arrays. Definições claras ajudam os desenvolvedores cliente a entender quais dados esperar e como analisá-los. Somente `JSON` e `XML` podem configurar schemas. Para obter informações detalhadas, consulte Schemas.
Exemplo	Fornecer uma resposta de exemplo é essencial para ilustrar como a API se comporta em cenários reais. Idealmente, um exemplo deve ser um conjunto de dados de amostra retornado pelo servidor quando o endpoint é acionado com uma requisição predefinida. Ele deve refletir a estrutura, o formato de dados e os tipos conforme definidos pelo schema da resposta.

Adicionar Respostas

Em geral, recomenda-se definir pelo menos uma resposta bem-sucedida e uma resposta de erro para cada endpoint na documentação da sua API. Essa prática garante cobertura abrangente de vários resultados potenciais, fornecendo aos desenvolvedores uma compreensão clara de como a API se comporta em diferentes cenários.

Clique no botão + Adicionar no canto superior direito do módulo Respostas para adicionar respostas.

Normalmente, no design de API, enquanto as respostas bem-sucedidas 200 OK frequentemente diferem entre vários endpoints devido a necessidades distintas de dados de saída, as respostas de erro, como 400 Bad Request e 404 Not Found, tendem a ser consistentes entre diferentes endpoints. O Apidog aborda de forma inteligente essa característica comum com seu recurso Componente de Resposta, que permite a reutilização de respostas de erro predefinidas, tornando o processo de documentação da API mais eficiente e o comportamento da API mais consistente.

Componentes de Resposta

Saiba mais sobre Componentes de Resposta.

Se um componente de resposta não for necessário, você pode optar por Adicionar Resposta em Branco para definir respostas exclusivas dentro de endpoints individuais.

Adicionar Exemplos de Resposta

Clique em "Adicionar Exemplo" para incluir exemplos de resposta no Apidog.

Uma única resposta pode acomodar vários exemplos diversos. Ao adicionar exemplos, forneça um nome para o exemplo e os dados de resposta correspondentes.

Geração Automática de Exemplos

Ao clicar em Gerar Automaticamente, o Apidog gerará dados de resposta razoáveis com base na definição do schema da resposta.

Visualizar o Endpoint

Após concluir a especificação do endpoint, clique em "Salvar" para salvar suas alterações. Em seguida, alterne para a aba "API" para visualizar o endpoint que você acabou de configurar.

Conceitos Básicos de Endpoint

Criar um Endpoint#

Caminho do Endpoint#

Método da Requisição#

Metadados do Endpoint#

Requisição#

Parâmetros da Requisição#

Parâmetros de Consulta#

Parâmetros de Caminho#

Parâmetros de Cabeçalho#

Parâmetros de Corpo#

Descrever Parâmetros#

Schemas#

Resposta e Exemplo#

Adicionar Respostas#

Adicionar Exemplos de Resposta#

Geração Automática de Exemplos#

Visualizar o Endpoint#

Criar um Endpoint

Caminho do Endpoint

Método da Requisição

Metadados do Endpoint

Requisição

Parâmetros da Requisição

Parâmetros de Consulta

Parâmetros de Caminho

Parâmetros de Cabeçalho

Parâmetros de Corpo

Descrever Parâmetros

Schemas

Resposta e Exemplo

Adicionar Respostas

Adicionar Exemplos de Resposta

Geração Automática de Exemplos

Visualizar o Endpoint