construção de API - procedimentos

[BrunoBit 82]

Faala rapaziiaada.

De acordo com o conhecimento de vocês, é necessário configurar os headers pra construção de uma API? Se sim, como você faz e pq?

Se tiver algum material de estudo que queira recomendar, fique à vontade.

 

Desde já agradeço rapaziada, abração e fiquem com Deus.

[Matheus Tavares 167]

@BrunoBit, vou precisar resumir um pouco a minha resposta, pq ando bem atarefado aqui (construindo uma API, justamente):

 

Uma API REST/RESTful (que imagino que seja isso que você quer) sem definição apropriada de cabeçalhos de resposta não é uma API. Veja: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

 

Alguns exemplos:

Sua aplicação retorna json? Você precisa definir Content-Type para application/json.

 

GET /produtos/35:

- Retornou um produto? Precisa retornar OK 200.

- Não retornou um produto? Retorne 404.

Veja esse diagrama: https://raw.githubusercontent.com/for-GET/http-decision-diagram/master/httpdd.png

PATCH /produtos/35
{
    "descrica": "nova descrição para o produto 35"
}

Observe o erro de digitação no parâmetro da requisição.

Essa requisição deve retornar Bad Request 400.

 

Eu estou construindo minha API em JS/Node.js por alguns requisitos do meu modelo de negócios, mas você não perde absolutamente nada escrevendo em PHP, se você utilizar a versão 7, que praticamente foi reescrita do zero e está muito mais rápida e otimizada (dizem que em torno de 10x).

Citei o Node exatamente pq é muito comum usarem ele para APIs e você com muita frequência vai/deve ouvir falar dele ao construir uma, mas quis já tirar essa sua dúvida se ela acabar brotando na sua cabeça em algum momento.

 

No contexto de PHP, construir uma classe Response para aplicação é super fácil... existem muitos exemplos e códigos prontos por aí.

Você ainda tem a opção de usar uma microframework. Extremamente comum para APIs. Exemplos: Silex e Lumen.

 

Ou, claro... simplesmente estudar essas respostas e implementar manualmente. Apenas a função header() já é suficiente nesse caso. Essa é a magia do PHP 

[BrunoBit 82]

Eu li aqui o artigo que você enviou, consegui compreender os princípios de uma API, mas eu to com dificuldade em entender como usar os headers, não consegui pegar a lógica de uso ainda, vou fazer uns testes, pq o que eu entendi sobre o header foi mais ou menos isso aqui:

$result = .. resultado de alguma query ..;

header('Content-Type: application/json');
if($result){
	header("HTTP/1.1 200 OK");
	echo json_encode($result);
} else {
	header("HTTP/1.1 404 Not found");
	echo json_encode(array("error" => "disparo algum erro"));
}

 

[Matheus Tavares 167]

@BrunoBit, você deveria dar uma olhada nas especificações dos headers. O material da W3C seria o ideal, mas é mais complicado, dentro de um assunto que deveria ser simples... nesse caso eu indico a Wikipedia mesmo, veja que rico esse material: https://en.wikipedia.org/wiki/List_of_HTTP_header_fields

 

Observe que há uma divisão entre "Cabeçalhos de resposta", "Cabeçalhos não-padronizados para request e/ou response" e "Cabeçalhos da requisição".

Você deve estudar os de resposta principalmente. Perceba que sempre há um FIELD e um VALUE (par chave/valor).

O status code você deveria definir usando a http_response_code(). Não é que não dê pra usar o header() nesse caso, mas essa função simplifica um pouco o processo.

 

Os outros cabeçalhos você mantém o padrão da função header, que ainda possui 2 atributos extras, que você deveria dar uma olhada no manual.

 

Para verificar os cabeçalhos de resposta (não apenas do seu site, mas dos outros também, para poder estudá-los), use as Feramentas de desenvolvedores (DevTools) dos navegadores. Vá em Network/Rede e procure pelos cabeçalhos de resposta da página (às vezes você precisa atualizar a página para garantir que apareça na lista).

Essa é a forma mais fácil, mas você ainda pode usar Postman, CURL e outras ferramentas.

[Matheus Tavares 167]

Outra coisa... a parte bacana das APIs (quando são bem escritas) é justamente o fato de que você não precisa (mas você pode, se quiser) informar que houve um erro ou que o registro não foi encontrado.

 

Quero dizer que, vamos supor, o recurso não foi encontrado: beleza, você joga o 404. Não precisa escrever nada no corpo da resposta, pois o 404 já indica tudo que o requisitante precisa saber.

 

Seu código então podia seguir esse padrão:

<?php
$result = '...';

if ( !$result ) {
    http_response_code( 404 );
    exit();//isso é "importante"... mas o mais correto seria usar Exception
}

header( 'Content-Type: application/json' );
echo json_encode( $result );

 

Mas eu ainda recomendo uma classe para isso:

 

Veja a do Symfony (tem muita tralha no meio, mas pode te ajudar): https://github.com/symfony/http-foundation/blob/master/Response.php

 

Veja a do Laravel tb (muito mais bem escrita, mas talvez um pouco difícil de entender à primeira vista): https://github.com/laravel/framework/tree/5.5/src/Illuminate/Http

 

E esse pacote, menor, mais simples, pra fazer o básico: https://gist.github.com/ewwink/f14474fd955801153c47

 

Vale a pena pesquisar pacotes de resposta http, pois para uso comum, apenas uma classe geralmente supre as necessidades.

[BrunoBit 82]

Perfeito matheuzão, vou estudar esse material que você mandou.

[Gabriel Heming 766]

Apenas reforçando, um microframework é uma excelente aposta para montar APIs e os chamados microserviços. As recomendações continuam as mesmas, Silex , Lumem e, com a adiação do, Zend Expressive.

 

Caso você escolha partir para algo próprio, deve estudar essa parte aqui também: http://php.net/manual/pt_BR/wrappers.php.php

 

Pois, por exemplo, um requisição POST não será recebida através da super-gloval $_POST, e sim através do seguinte código:

file_get_contents("php://input");