REST API - guia desen web PYTHON

Prévia do material em texto

{REST}
API COM
FLASK
L I V R O I
GUIA DE DESENVOLVIMENTO
WEB
A N D R Á S H A R T M A N N P A T A K I
C O N F I G E H T T P
Este livro tem como objetivo, introduzir
programadores intermediários em Python para o
desenvolvimento Web com o MicroFrameWork
Flask. Vale lembrar que a palavra "Micro" não faz
referência a algo mínusculo, que serve apenas para
objetivos básicos de protótipagem ou teste, e sim
devido a sua simplicidade de uso baseado na
capacidade de extensão; Flask foi escrito em
Linguagem Python por Armin Ronacher, e já possui
mais de 10 anos de amadurecimento desde o seu
primeiro release (2010). 
Vários são os tipos de Web-Services possíveis de
serem desenvolvidos, desde um simples blog de
postagens diárias, até um E-commerce bem
estruturado como da Amazon. Infinitas são e serão
as possibilidades, e essa é a melhor parte em ser
um Desenvolvedor Web.
No caso, este material terá como foco lecionar todo
o básico exigido para programar APIs-Rest, seja qual
for seu segmento; Fato é, que estamos no mundo
em que as APIs são capazes de nos prestar serviços
inimagináveis e de alta escalabilidade, desde
mostrar a previsão do tempo, até realizar
pagamentos. Caso você ainda não saiba o que é
uma API e como ela funciona, fique tranquilo que
este material vai te ajudar com isso.
Sobre este Guia
Foco do Material
Configuração do Ambiente...........................4
Instalando Python no Windows...................4
Criando VirtualEnv no Windows..................5
Instalando Python no Linux.........................7
Criando VirtualEnv no Linux.........................8
Conclusão..........................................................9
Protocolo HTTP...............................................10
Métodos de um Request..............................11
Respostas do Servidor..................................12
API-REST...........................................................15
Query-String....................................................16
Conclusão........................................................17
Servir para ser servidor................................18
INDEX
Facilite suas consultas no livro acessando este indíce.
Para iniciarmos a construção do projeto, é
necessário assegurarmos que o Python esteja
instalado em seu sistema, para em sequência,
criarmos um Ambiente Virtual e instalar o Flask; Dessa
forma, podemos deixar um Script pré-configurado
alocado em um espaço exclusivo para este projeto,
assim testaremos algumas requisições. Caso já
tenha feito isso, sinta-se livre para pular este
capitulo.
Primeiramente acesse o link:
https://www.python.org/downloads/ e faça o
download da versão que se encontra mais
atualizada. Execute o instalador e siga os passos do
assistente virtual; Ao terminar, é bem provavel que
seu Python tenha sido instalado com sucesso,
lembre-se que em caso de falhas, fique atento aos
problemas relacionados com o "PATH".
Em sequência, é fundamental instalarmos o
gerenciador de pacotes do Python, conhecido
apenas como PIP; Através dele podemos adicionar
novas extensões à linguagem e gerenciá-las. 
Para começar, abra o seu Prompt de Comando no
modo de administrador e digite o seguinte
argumento:
Capítulo I - Criando seu ambiente de
desenvolvimento
Instalando o Python no Windows
C:\Users\andras> python -m ensurepip
Quando terminar a execução, ele provavelmente vai
apresentar uma mensagem de sucesso informando
que foi instalado. No entanto, o PIP esta sempre
recebendo atualizações esporádicas, por isso faz
necessário executar o seguinte argumento para
atualiza-lo:
O Ambiente Virtual é um recurso especial do Python
para trabalhar com diversos Projetos no seu sistema,
pois permite a possibilidade de passar uma
configuração exclusiva para cada um. Através de um
VirtualEnv você pode alternar as versões da
linguagem e gerenciar de forma mais adequada as
extensões necessárias ao seu projeto. 
Para instalar um virtualenv no Windows, digite o
seguinte argumento em seu Prompt de Comando:
Criando Virtualenv no Windows
C:\Users\andras> python -m ensurepip --
upgrade
Agora que o Pip esta instalado, podemos criar o
nosso VirtualEnv para este projeto.
C:\Users\andras>c:\Python38\Scripts\pip.e
xe install virtualenv
O Atenção a versão do Python que estiver instalado
em sua máquina. Neste livro, usaremos como
exemplo a 3.8, porém se necessário, efetue a
substituição
Tendo realizado os últimos passos com sucesso,
escolha qualquer local do seu sistema e crie uma
pasta chamada: my_first_api. É dentro dela onde
colocaremos os arquivos para o nosso projeto
executar. Com seu Prompt de Comando aberto,
navegue para dentro do recém diretório criado
(my_first_api) e execute o seguinte argumento:
C:\Users\Documents\andras\my_first_api>
c:\Python38\Scripts\virtualenv.exe venv
Através desse comando, estamos avisando ao
virtualenv.exe criar uma pasta chamada venv e
instalar o Python dentro dela. 
Quando encerrar a execução, devemos ativar o
ambiente virtual através de outro argumento. Isso é
necessário para que o nosso Prompt de Comando
entre no contexto do ambiente criado. Digite abaixo:
C:\Users\Documents\andras\my_first_api>
venv\Scripts\activate
Se tudo tiver corrido bem, seu Prompt ficará
semelhante a isso:
(venv)
C:\Users\andras\Documents\my_first_api>
Dessa forma, estaremos prontos para começar a
desenvolver o projeto.
Instalando Python no Fedora(Linux)
Normalmente, o Python já vem instalado na maioria
das distribuições baseadas em Linux, uma vez que
os sistemas estão adotando a linguagem para
determinadas aplicações. Você pode verificar se o
Python está instalado passando o seguinte
argumento no seu Terminal:
[andras@localhost:~]$ which python
Por padrão, ele deve retornar algo como:
/usr/bin/python , o que significa que a linguagem está
instalada. Entretanto, se você receber alguma coisa
assim: which : no python in /usr/local/... Precisaremos
instala-lá, para isso siga os próximos passos.
Para usuários do Fedora, é possivel fazer a
instalação da Linguagem através do gerenciador de
pacotes dnf . Caso você seja de outra distribuição
Linux como o Ubuntu, utilize o apt. Em caso de
dúvidas, consulte o nome do seu repósitório. Para
esse livro, usaremos o Fedora como exemplo.
 
[andras@localhost:~]$ sudo dnf install
python3.8
Em caso de outra versão, apenas substitua pelo
número correspondente.
Com o término da execução, podemos instalar o PiP.
Caso você não tenha lido a ultima sessão, o PIP é o
gerenciador de Pacotes do Python que serve para
instalar novas extensões e gerenciá-las. Para instala-
lo, digite o seguinte argumento:
[andras@localhost:~]$ sudo pip3 install
python-pip
Não é necessário configurar váriaveis de Ambiente
em sistema Linux, portanto nos adiantemos.
Criando Virtualenv no Fedora
Como já explicado no Tutorial de instalação o
Windows, o que é o VirtualEnv, podemos seguir
direto para a instalação; Digite o seguinte comando
para começar:
[andras@localhost:~]$ sudo pip3 install
virtualenv
Como de prática, crie uma pasta chamada
my_first_api no local de sua escolha, e através do seu
Terminal navegue para dentro do diretório recém
criado. Feito isto, digite o comando a seguir:
[andras@localhost:~/my_first_api]$
source env/bin/activate
Este argumento devera ativar nosso ambiente
virtual, fazendo com que nosso Terminal atue dentro
do env.
Neste capitulo, aprendemos a instalar o Python em
dois sistemas distintos (Windows e Linux); Também
instalamos o gerenciador de Pacotes PIP para
baixarmos as bibliotecas que faremos uso ao longo
deste material. É importante lembrar que
aprendemos a criar e ativar nosso próprio ambiente
virtual, e assim estamos preparados para dar os
primeiros passos com o Flask. No entanto, como o
foco desse guia é o desenvolvimento de APIs-REST,
farei no próximo capitulo uma introdução básica ao
funcionamento do Protocolo HTTP, que é de
extrema importância para o Mindset da nossa
aplicação.
Se tudo tiver corrido bem, seu Terminal estará
proximo a isso:
(venv) [andras@localhost:~]$ 
ConclusãoVamos avançar?
O HTTP, comumente referenciado no inicio de uma
URL, é um protocolo que permite a obtenção dos
recursos disponiveis na internet. O mesmo é
considerado uma base comum na troca de dados
entre cliente e servidor.
Seu funcionamento pode ser exemplificado como
um envio de cartas; A URL é passada como
parâmetro para informar o destinátario (Servidor do
Domínio), onde no remetente estão as informações
da nossa máquina, como o IP e o Horário da
requisição; No Corpo da carta podemos ainda
escrever alguma mensagem,como uma receita de
bolo ou alguma lista de produtos. 
Quando a "carta" é enviada, obtemos
simultaneamente uma resposta do envio, contendo
todas as informações que precisamos. 
Toda essa dinâmica ocorre simultaneamente
quando acessamos algum site com o navegador. 
Capítulo II - O Protocolo HTTP
Request
Response
Inicio da Conexão
Fim da Conexão
O HTTP Possui unicamente 2 estados possíveis:
Como ilustrado na imagem acima, a requisição é
quem abre uma conexão direta entre cliente e
servidor; Comumente ocorre de forma discreta nos
navegadores quando se acessa uma URL.
No entanto, uma requisição pode passar um
método, que seria como uma diretriz apontando
uma ação especifica a ser processada pelo servidor;
Vale mencionar que apenas um método pode ser
executado por vez. 4 delas são as principais mais
executadas em todo o mundo. Veja abaixo:
GET > Informa ao servidor que a intenção do Cliente
é apenas visualizar algum conteúdo.
POST > Informa que o cliente estará enviando
alguma informação para o servidor.
PUT > Informa que o cliente pretende atualizar
alguma informação(No Caso ela Inteira).
DELETE > Informa para o servidor que o cliente
pretende excluir algum conteúdo.
Caso você ainda esteja com dúvidas, sugiro que você
consulte materiais externos relacionados aos
métodos do Protocolo HTTP, uma boa sugestão
seria acessar este site: http://gabsferreira.com/os-
metodos-http-e-a-diferenca-entre-eles/
Métodos de uma Requisição 
Ao Submetermos algum método para o servidor, o
mesmo estará incubido da função de processar essa
requisição, e nos fornecer alguma resposta válida.
Porém nem sempre a resposta vai condizer com o
esperado, e é nesse momento que aparecem as
páginas de erro. Para que o Cliente identifique de
forma mais especifica o estado de uma requisição,
foi elaborado os códigos de status HTTP. Esses
códigos são passados pelo <HEADER> da resposta,
Veja alguns mais frequentes abaixo:
200 OK indica que a requisição foi bem sucedida.
201 OK A requisição e a criação de um recurso 
foram bem sucedidas.
404  Essa resposta indica que o recurso requisitado
não pode ser encontrado.
401 Esse erro indica que você precisa estar
autenticado para acessar o recurso.
500 quando o processamento falha devido a
problemas internos do servidor.
Existe uma lista completa de códigos de Status Http.
Você pode verificar ela através desse link:
https://www.hostinger.com.br/tutoriais/o-que-e-http-
error-e-principais-codigos-http/
Respostas do Servidor 
Talvez você tenha percebido na ultima página, que
eu mencionei uma palavra um tanto estranha:
<HEADER>, saiba que fiz isso propositalmente pois
servirá como gatilho para a nosso próximo assunto.
Tanto em uma Resposta quanto em uma requisição,
estamos enviando um longo corpo de informações
estruturadas à serem recebidas. É importante que
nesse momento, nos asseguremos em estudar e
entender como funciona essa estrutura. Veja abaixo
a ilustração:
Parece um pouco absurdo ilustrar dessa forma, mas é a maneira mais facil que
encontrei para facilitar a compreensão. 
Através da Request-Line é passado o Método da
requisição, cujo é o unico campo obrigatório estar
informado. Exemplo:
GET http://google.com/ HTTP/1.1
No Escopo da Requisição e Resposta 
<-- Request-Line(Apenas em
Requests!)
<-- Header
<-- Body
Nos Headers está declarado majoritariamente as
informações relacionadas a identificação das partes,
como o IP, Horário, nome do sistema operacional e
até o tipo de conteúdo sendo enviado/recebido
entre Cliente e servidor. São vários os Headers que
podem ser acrescentados, porém os mais comuns
são:
Accept-Encoding: gzip, deflate
Accept-Language
User-Agent
Cookies
...
Por fim, é no body que será apresentado todo o
conteúdo de um site. O formato da informação
enviada como resposta para o cliente, é o verdadeiro
divisor de águas entre um Web Service Habitual e
uma API. Comumente a Resposta de um Site é
retornada em HTML (Hyper Text Markup Language)
que é responsavel em estruturar uma página inteira.
Usar apenas o Html para montar páginas, pode causar uma má
impressão, uma vez que o mesmo serve apenas como esqueleto.
Para embelezar, o CSS é a opção mais difundida no mundo.
Uma API-REST, sendo Rest um acrônimo para
Representational State Transfer, nada mais é do
que um serviço baseado nos métodos
fundamentais do protocolo Http. A Resposta de
uma API geralmente será um JSON(Javascript object
Notation). Através de uma resposta em Json, é
possível organizar de maneira mais prática e leve os
dados. Veja um exemplo:
(request) GET -> http://www.feira.com/frutas
...
(response):[
{"id": 1, "nome": "melancia"},
{"id": 2, "nome": "melao"},
{"id": 3, "nome": "laranja"},
{"id": 4, "nome": "banana"}
{"id": 5, "nome": "pera"}
]
Uma requisição do tipo GET foi feita para uma API
que serve dados de uma Feira convencional. O
Endpoint especificado foi o setor de Frutas, e como
resposta o servidor enviou um JSON listando
diversas delas, separado por nome e id. 
Um Endpoint nada mais é do que o último termo
digitado na URL que vai remeter algum serviço a ser
desempenhado pela API. 
A estrutura de um Json é simples de entender, o
mesmo é constituido de um agrupamento baseado
de chaves e valores. 
API-REST 
A Chave de um Json geralmente se mantém estática
na maioria dos casos, pois age como um
identificador para o valor do objeto. Por exemplo, se
fosse para fazer um Json do meu documento
pessoal, seria algo assim:
{"nome": "Andras", "idade": 20}
Faz-se necessário mencionar que toda e qualquer
string declarada em um Json, deve estar dentro de
Aspas duplas, como especificado no ECMA-404. 
Quando acessamos um Site que disponibiliza
diversos tipos de dados relacionados (geralmente
em grande quantidade), podemos melhorar a nossa
pesquisa usando os filtros de busca. Esses filtros
discretamente são passados na URL da requisição
quando preenchidos na página; Um exemplo disso
seria uma imobiliária online, onde inúmeras casas
de regiões distintas estão cadastradas no banco de
dados; Se quisermos procurar uma casa próxima a
nossa localização, cujo valor seja menor que R$
1.000.000, precisaremos de antemão informar esse
critério nos filtros de busca. Ao executar a
requisição, os valores preenchidos são passados
automaticamente na URL, e nesse momento
chamamos eles de Query-String. Exemplo: 
GET → http://imoveis.com/casas?
regiao=saopaulo?preco=-1.000.000
 
Query-String 
De forma similar ao JSON, a Query-String também
funciona com base em chave e valores, onde após o
ponto de interrogação(?) está a chave da pesquisa,
sendo igualada(=) ao valor digitado. 
 
Nesse capítulo mais extenso, foi lecionado o
funcionamento do Protocolo HTTP juntamente com
seus vários recursos, dentre estes, demos um foco 
 especial para abordar a arquitetura REST em
Aplicações Web. Vale mencionar que entramos no
escopo da Requisição e Resposta e abordamos a
distinção entre ambos.
Antes que prossigamos para o próximo capitulo,
queria trazer algumas curiosidades para a
conclusão desse tema; Saiba que aplicações que
seguem a finco o conceito REST, são conhecidas
como RESTFUL, cujo este termo foi criado
especificamente para distinguir as novas aplicações,
de antigas mais consolidadas.
O HTTP não é o único protocolo utilizado no
mundo, pois ele também oferece algumas
limitações. No caso de aplicações em tempo real
como Chats de Bate-Papo ou Jogos Online,
dependemos de uma conexão que se mantenha
constante a todo o momento;Para estes, existem os
WebSockets, que vão serresponsáveis em criar um
tunel de conexão persistente, e desse modo não se
faz necessário executar novas requisições.
 
Conclusão 
Essa parábola é explicitamente uma paródia ao
versículo biblíco original, e de fato essa frase faz
muito sentido quando trabalhamos com uma API;
Nem sempre nossa aplicação vai estar servindo
dados, dependendo do segmento adotado, se faz
necessário que nossa própria API se comunique
com outra de terceiros, afim de realizar algum
pagamento ou informar alguma mudança de
estado.
Portanto no próximo livro, vamos aprender como se
conectar com uma API real e testar todos os
métodos, isto é, criando nosso próprio script e
instalando a biblioteca:
Receber para servir, e servir para ser
Servidor. 
Te vejo no
próximo livro!