O que é uma Requisição Put em API (Guia Mais Recente de 2024)

Neste post de blog, vamos discutir tudo o que você precisa saber sobre API e requisições PUT. Começaremos explicando o que é uma API e depois mergulharemos no que é uma requisição PUT e como ela difere de outros métodos HTTP, como POST.

Forneceremos algumas melhores práticas e formatos de resposta comuns para API, e mostraremos como fazer uma requisição PUT no Apidog.

Então, sem mais delongas, vamos mergulhar no mundo das APIs e requisições PUT!

O que é uma API?

Uma API, ou Interface de Programação de Aplicações, é um conjunto de regras definidas que permite que diferentes aplicações se comuniquem entre si. É como um garçom que anota seu pedido e o comunica à cozinha e depois traz sua comida de volta para você. APIs ajudam diferentes componentes de software a se comunicarem e transferirem dados de forma fácil e segura. Elas são como o molho secreto que torna o desenvolvimento de software e inovação mais simples e eficiente.

Por exemplo, quando você usa um aplicativo móvel para reservar uma corrida, o aplicativo usa uma API para se comunicar com os servidores do serviço de transporte para obter a localização do motorista, tempo estimado de chegada e outros detalhes. Isso ajuda o aplicativo a exibir as informações para você em tempo real.

Em resumo, as APIs são como a cola que mantém diferentes componentes de software unidos, permitindo que funcionem de forma integrada e eficiente.

O que é uma requisição PUT?

Uma requisição PUT é um método de requisição HTTP que é usado para atualizar ou substituir um recurso existente no servidor. Uma requisição PUT cria um novo recurso ou substitui uma representação do recurso alvo com o payload da requisição.

A requisição tem um corpo e a resposta bem-sucedida tem um corpo. A requisição PUT não é segura e é idempotente. Não é permitida em formulários HTML. Aqui está um exemplo de uma requisição PUT:

PUT /new.html HTTP/1.1
Host: example.com
Content-type: text/html
Content-length: 16

<p>Novo Arquivo</p>

Se o recurso alvo não tiver uma representação atual e a requisição PUT criar uma com sucesso, o servidor de origem deve informar o agente do usuário enviando uma resposta 201 (Criado). Se o recurso alvo tiver uma representação atual e essa representação for modificada com sucesso de acordo com o estado da representação inclusa, então o servidor de origem deve enviar uma resposta 200 (OK) ou 204 (Sem Conteúdo) para indicar a conclusão bem-sucedida da requisição.

Como funciona uma requisição PUT?

Quando você faz uma requisição HTTP PUT e o Request-URI aponta para um recurso existente, o servidor substitui completamente esse recurso com os dados contidos no corpo da requisição PUT. Se o Request-URI não apontar para um recurso existente, o servidor pode criar o recurso com essa URL.

Requisições PUT vs POST

A diferença entre uma requisição PUT e uma requisição POST é que uma requisição PUT é idempotente, ou seja, chamá-la uma vez ou várias vezes sucessivamente tem o mesmo efeito (ou seja, sem efeito colateral), enquanto requisições POST idênticas sucessivas podem ter efeitos adicionais, semelhante a fazer um pedido várias vezes. Requisições PUT são usadas para atualizar ou substituir um recurso existente no servidor, enquanto requisições POST são usadas para adicionar um recurso no servidor.

Como Enviar uma Requisição PUT em uma API

Para enviar uma requisição PUT em uma API, você precisa especificar o método HTTP como PUT e a URL do recurso que deseja atualizar ou substituir. Você também precisa incluir a representação atualizada do recurso no payload da requisição. Aqui está um exemplo de uma requisição PUT em Python usando a biblioteca requests:

import requests

url = 'https://example.com/api/resource/1'
data = {'key': 'value'}

response = requests.put(url, json=data)

Neste exemplo, o método requests.put() envia uma requisição PUT para a URL especificada com a representação atualizada do recurso no parâmetro data. A resposta do servidor é armazenada na variável response.

Criando e Testando uma Requisição PUT no Apidog

Apidog é uma plataforma integrada de colaboração para documentação de API, depuração de API, simulação de API e testes automatizados de API que combina Postman, Swagger, Mock e JMeter para lidar com o problema de sincronização de dados entre diferentes sistemas usando um conjunto de sistemas e um conjunto de dados.

É uma plataforma de colaboração de API tudo-em-um que fornece documentação de API, depuração de API, simulação de API e testes automatizados de API. Com um único sistema e dados centralizados, o Apidog resolve o problema de sincronização de dados entre vários sistemas. Uma vez que o documento da API é definido, a depuração de API, simulação de dados e testes de API podem ser utilizados diretamente sem a necessidade de redefinição.

Para criar e testar uma requisição PUT no Apidog, você pode seguir estes passos:

1. Abra o Apidog: Abra o Apidog e crie uma nova requisição.

2. Especifique o método HTTP: Selecione PUT como o método HTTP.

3. Defina a URL da requisição: Insira a URL do recurso que você deseja atualizar, adicione cabeçalhos da requisição e/ou o corpo da requisição. Então clique no botão “Enviar” para enviar a requisição PUT.

4. Verifique a resposta: Verifique a resposta do servidor para garantir que a requisição PUT foi bem-sucedida.

Melhores Práticas para Usar Requisições PUT em API

Aqui estão algumas melhores práticas para usar requisições PUT em uma API:

1. Use um formato de resposta consistente: É uma boa ideia usar um formato de resposta consistente para todos os seus endpoints, incluindo requisições PUT. Isso pode tornar mais fácil para os clientes entenderem e trabalharem com sua API.
2. Garanta que as atualizações sejam idempotentes: Operações idempotentes são aquelas que podem ser repetidas várias vezes sem causar efeitos indesejados. Requisições PUT são idempotentes, o que significa que chamá-las uma vez ou várias vezes sucessivas tem o mesmo efeito. Isso ocorre porque o payload da requisição contém a representação atualizada do recurso. Se o recurso não existir, um novo recurso é criado com a representação especificada.
3. Organize o design da API em torno de recursos: APIs REST são projetadas em torno de recursos, que são qualquer tipo de objeto, dado ou serviço que pode ser acessado pelo cliente. Um recurso tem um identificador, que é uma URI que identifica exclusivamente esse recurso. Por exemplo, a URI para um pedido de cliente específico pode ser: https://example.com/orders/1.
4. Defina operações de API em termos de métodos HTTP: APIs REST usam métodos HTTP padrão para realizar operações em recursos. As operações mais comuns são GET, POST, PUT, PATCH e DELETE. Requisições PUT são usadas para atualizar ou substituir um recurso existente no servidor, enquanto requisições POST são usadas para adicionar um recurso no servidor.
5. Conforme-se com a semântica HTTP: APIs REST devem se conformar com a semântica HTTP. Por exemplo, requisições PUT devem ser usadas para atualizar ou substituir um recurso existente, enquanto requisições POST devem ser usadas para adicionar um recurso no servidor. Isso ajuda a garantir que sua API seja consistente e fácil de usar.

Alguns formatos de resposta comuns da requisição PUT

O formato de resposta para uma requisição PUT depende do design da API e do caso de uso específico. No entanto, é uma boa prática usar um formato de resposta consistente para todos os seus endpoints, incluindo requisições PUT. Aqui estão alguns formatos de resposta comuns para requisições PUT:

1. Código de status HTTP 200 OK: Este código de status é retornado para um PUT bem-sucedido de uma atualização em um recurso existente. Nenhum corpo de resposta é necessário. O código de status HTTP 204 Sem Conteúdo é ainda mais apropriado.
2. Código de status HTTP 201 Criado: Este código de status é retornado para um PUT bem-sucedido de um novo recurso, com a URI mais específica para o novo recurso retornada no campo de cabeçalho Location e outras URIs e metadados relevantes do recurso refletidos no corpo da resposta.
3. Código de status HTTP 409 Conflito: Este código de status é retornado para um PUT que não é bem-sucedido devido a uma modificação de terceiro, com uma lista de diferenças entre a atualização tentada e o recurso atual no corpo da resposta.
4. Código de status HTTP 400 Solicitação Inválida: Este código de status é retornado para um PUT que não é bem-sucedido, com texto em linguagem natural (como inglês) no corpo da resposta que explica por que o PUT falhou.

Conclusão

Neste post de blog, aprendemos sobre PUT, um método HTTP que é usado para criar ou atualizar um recurso em um servidor. É usado para atualizar o registro existente, e se o registro não existir, cria um novo. A diferença fundamental entre as requisições POST e PUT é refletida nos diferentes significados do Request-URI.

Ao projetar uma API, é importante usar o método correto dependendo do objeto que você está referenciando na requisição. Se você nomear explicitamente a URL dos objetos que cria, então use PUT.

Além disso, aprendemos como criar e testar APIs usando o Toolkit de Desenvolvimento de API Apidog. Este toolkit permite que você projete e desenvolva APIs mais rápido e em conjunto. 🚀