CRUD API

CRUD API
Vimos exemplos de um aplicativo da web City Search que usa parâmetros PHP para pesquisar o nome de uma cidade nas seções anteriores. Esta seção verá como tal aplicativo da web pode utilizar APIs para realizar a mesma coisa e interagiremos diretamente com o endpoint da API.

APIs
Existem vários tipos de APIs. Muitas APIs são usadas para interagir com um banco de dados, de modo que poderíamos especificar a tabela solicitada e a linha solicitada em nossa consulta de API e, em seguida, usar um método HTTP para executar a operação necessária. Por exemplo, para o endpoint api.php em nosso exemplo, se quiséssemos atualizar a tabela de cidades no banco de dados, e a linha que atualizaremos tiver o nome da cidade Londres, então o URL seria mais ou menos assim:

curl -X PUT http://<SERVER_IP>:<PORT>/api.php/city/london ...SNIP...
 

CRUD
Como podemos ver, podemos facilmente especificar a tabela e a linha na qual queremos realizar uma operação por meio dessas APIs. Então podemos utilizar diferentes métodos HTTP para realizar diferentes operações nessa linha. Em geral, as APIs realizam 4 operações principais na entidade de banco de dados solicitada:

• Operação: Create. 
• HTTP Method: POST. 
• Descrição: Adiciona os dados especificados à tabela do banco de dados.

Read: GET: Lê a entidade especificada na tabela do banco de dados.

Update: PUT: Lê a entidade especificada na tabela do banco de dados.

Delete: DELETE: Remove a linha especificada da tabela do banco de dados.

Essas quatro operações estão principalmente vinculadas às APIs CRUD comumente conhecidas, mas o mesmo princípio também é usado em APIs REST e em vários outros tipos de APIs. É claro que nem todas as APIs funcionam da mesma maneira, e o controle de acesso do usuário limitará quais ações podemos realizar e quais resultados podemos ver. O módulo Introdução às Aplicações Web explica melhor esses conceitos, portanto você pode consultá-lo para obter mais detalhes sobre APIs e seu uso.

READ
A primeira coisa que faremos ao interagir com uma API é ler dados. Conforme mencionado anteriormente, podemos simplesmente especificar o nome da tabela após a API (por exemplo, /cidade) e então especificar nosso termo de pesquisa (por exemplo, /london), como segue:

[!bash!]$ curl http://<SERVER_IP>:<PORT>/api.php/city/london

[{"city_name":"London","country_name":"(UK)"}]

Vemos que o resultado é enviado como uma string JSON. Para formatá-lo corretamente no formato JSON, podemos canalizar a saída para o utilitário jq, que irá formatá-lo corretamente. Também silenciaremos qualquer saída cURL desnecessária com -s, como segue:

[!bash!]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/london | jq

[
  {
    "city_name": "London",
    "country_name": "(UK)"
  }
]

Como podemos ver, obtivemos a saída em uma saída bem formatada. Também podemos fornecer um termo de pesquisa e obter todos os resultados correspondentes:

[!bash!]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/le | jq

[
  {
    "city_name": "Leeds",
    "country_name": "(UK)"
  },
  {
    "city_name": "Dudley",
    "country_name": "(UK)"
  },
  {
    "city_name": "Leicester",
    "country_name": "(UK)"
  },
  ...SNIP...
]

Finalmente, podemos passar uma string vazia para recuperar todas as entradas da tabela:

 

[!bash!]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/ | jq

[
  {
    "city_name": "London",
    "country_name": "(UK)"
  },
  {
    "city_name": "Birmingham",
    "country_name": "(UK)"
  },
  {
    "city_name": "Leeds",
    "country_name": "(UK)"
  },
  ...SNIP...
]

Tente visitar qualquer um dos links acima usando seu navegador para ver como o resultado é renderizado.

CREATE
Para adicionar uma nova entrada, podemos usar uma solicitação HTTP POST, que é bastante semelhante ao que realizamos na seção anterior. Podemos simplesmente POST nossos dados JSON e eles serão adicionados à tabela. Como esta API usa dados JSON, também definiremos o cabeçalho Content-Type como JSON, da seguinte maneira:

[!bash!]$ curl -X POST http://<SERVER_IP>:<PORT>/api.php/city/ -d '{"city_name":"HTB_City", "country_name":"HTB"}' -H 'Content-Type: application/json'

Agora podemos ler o conteúdo da cidade que adicionamos (HTB_City), para ver se ela foi adicionada com sucesso:

[!bash!]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/HTB_City | jq

[
  {
    "city_name": "HTB_City",
    "country_name": "HTB"
  }
]

 Como podemos ver, foi criada uma nova cidade, que antes não existia.

Exercício: Tente adicionar uma nova cidade através do devtools do navegador, usando uma das solicitações Fetch POST que você usou na seção anterior.

UPDATE
Agora que sabemos como ler e escrever entradas através de APIs, vamos começar a discutir dois outros métodos HTTP que não usamos até agora: PUT e DELETE. Conforme mencionado no início da seção, PUT é usado para atualizar entradas de API e modificar seus detalhes, enquanto DELETE é usado para remover uma entidade específica.

Nota: O método HTTP PATCH também pode ser usado para atualizar entradas de API em vez de PUT. Para ser mais preciso, PATCH é usado para atualizar parcialmente uma entrada (modificar apenas alguns de seus dados "por exemplo, apenas nome_cidade"), enquanto PUT é usado para atualizar a entrada inteira. Também podemos usar o método HTTP OPTIONS para ver qual dos dois é aceito pelo servidor e, em seguida, usar o método apropriado de acordo. Nesta seção, focaremos no método PUT, embora seu uso seja bastante semelhante.

Usar PUT é bastante semelhante a POST neste caso, com a única diferença que temos que especificar o nome da entidade que queremos editar na URL, caso contrário a API não saberá qual entidade editar. Então, tudo o que precisamos fazer é especificar o nome da cidade na URL, alterar o método de solicitação para PUT e fornecer os dados JSON como fizemos com o POST, da seguinte forma:

[!bash!]$ curl -X PUT http://<SERVER_IP>:<PORT>/api.php/city/london -d '{"city_name":"New_HTB_City", "country_name":"HTB"}' -H 'Content-Type: application/json'

Vemos no exemplo acima que primeiro especificamos /city/london como nossa cidade e passamos uma string JSON que continha "city_name":"New_HTB_City" nos dados da solicitação. Portanto, a cidade de Londres não deveria mais existir, e uma nova cidade com o nome New_HTB_City deveria existir. Vamos tentar ler ambos para confirmar:

[!bash!]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/london | jq

[!bash!]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/New_HTB_City | jq

[
  {
    "city_name": "New_HTB_City",
    "country_name": "HTB"
  }
]

Na verdade, substituímos com sucesso o nome da cidade antiga pela nova cidade.

Nota: Em algumas APIs, a operação Update também pode ser usada para criar novas entradas. Basicamente, enviaríamos nossos dados e, se não existissem, os criaríamos. Por exemplo, no exemplo acima, mesmo que não existisse uma entrada com a cidade de Londres, seria criada uma nova entrada com os detalhes que passamos. No nosso exemplo, entretanto, este não é o caso. Tente atualizar uma cidade inexistente e veja o que você conseguiria.

DELETE
Por fim, vamos tentar deletar uma cidade, o que é tão fácil quanto ler uma cidade. Simplesmente especificamos o nome da cidade para a API e usamos o método HTTP DELETE, e isso excluiria a entrada, da seguinte forma:

[!bash!]$ curl -X DELETE http://<SERVER_IP>:<PORT>/api.php/city/New_HTB_City

[!bash!]$ curl -s http://<SERVER_IP>:<PORT>/api.php/city/New_HTB_City | jq
[]

Como podemos ver, após excluirmos New_HTB_City, obtemos um array vazio quando tentamos lê-lo, o que significa que ele não existe mais.

Exercício: Tente excluir qualquer uma das cidades adicionadas anteriormente por meio de solicitações POST e, em seguida, leia todas as entradas para confirmar se foram excluídas com sucesso.

Com isso, conseguimos realizar todas as 4 operações CRUD através do cURL. Em uma aplicação web real, tais ações podem não ser permitidas para todos os usuários, ou seria considerada uma vulnerabilidade se alguém pudesse modificar ou excluir qualquer entrada. Cada usuário teria certos privilégios sobre o que pode ler ou escrever, onde escrever se refere a adicionar, modificar ou excluir dados. Para autenticar nosso usuário para usar a API, precisaríamos passar um cookie ou um cabeçalho de autorização (por exemplo, JWT), como fizemos em uma seção anterior. Fora isso, as operações são semelhantes às que praticamos nesta seção.

 https://academy.hackthebox.com/module/35/section/227

 https://www.youtube.com/watch?v=vnM8-jqnq-8&t=2356s