91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
---
|
||
title: REST APIs with Falcon
|
||
localeTitle: APIs REST com Falcon
|
||
---
|
||
## Introdução
|
||
|
||
As APIs RESTful são um componente importante de qualquer pilha bem arquitetada, e o Python tem algumas estruturas brilhantes para compor rapidamente APIs. Um desses frameworks é chamado [Falcon](https://falconframework.org) - e é ótimo! Essencialmente um microframework, ele vem com um número considerável de vantagens:
|
||
|
||
1. É rápido. Muito depressa. Confira os benchmarks [aqui](https://falconframework.org/#sectionBenchmarks) .
|
||
|
||
2. Recursos HTTP são definidos como classes, com métodos de classe sendo usados para diferentes operações REST nesses recursos. Isso ajuda a manter uma base de código limpa.
|
||
|
||
3. É bastante extensível - confira [esta seção](https://github.com/falconry/falcon/wiki/Complementary-Packages) em seu wiki, para ter uma idéia.
|
||
|
||
4. Ele é baseado no WSGI - o padrão Python para aplicativos da web - e funciona com o Python 2.6, 2.7 e 3.3+. E se você precisar de mais desempenho, execute-o usando o PyPy!
|
||
|
||
|
||
## Começando
|
||
|
||
Primeiro, vamos preparar nosso ambiente. Pessoalmente, é sempre bom trabalhar em ambientes virtuais - você pode usar `virtualenv` , `virtualenvwrapper` ou `venv` . Em seguida, instale o Falcon usando o `pip` : `pip install falcon` .
|
||
|
||
Vamos desenvolver uma pequena amostra de API que faz manipulações muito básicas de fuso horário para nós. Ele exibirá a hora atual em UTC, assim como a hora da época correspondente. Para esse fim, vamos pegar uma biblioteca bacana chamada `arrow` : `pip install arrow` .
|
||
|
||
Você pode encontrar a amostra finalizada em [https://github.com/rudimk/freecodecamp-guides-rest-api-falcon](https://github.com/rudimk/freecodecamp-guides-rest-api-falcon) .
|
||
|
||
## Recursos
|
||
|
||
Pense em um recurso como uma entidade que sua API precisa manipular. No nosso caso, o melhor recurso seria um `Timestamp` . Nosso roteamento normalmente seria algo assim:
|
||
```
|
||
GET /timestamp
|
||
```
|
||
|
||
Aqui, `GET` é o verbo HTTP usado para chamar esse terminal, e `/timestamp` é o próprio URL. Agora que conseguimos esse pouco fora do caminho, vamos criar um módulo!
|
||
|
||
`$ touch timestamp.py`
|
||
|
||
Hora de importar a biblioteca do Falcon:
|
||
|
||
```python
|
||
import json
|
||
|
||
import falcon
|
||
|
||
import arrow
|
||
```
|
||
|
||
Note que também importamos o pacote `json` e a biblioteca de `arrow` . Agora, vamos definir uma classe para o nosso recurso:
|
||
|
||
```python
|
||
class Timestamp(object):
|
||
|
||
def on_get(self, req, resp):
|
||
payload = {}
|
||
payload['utc'] = arrow.utcnow().format('YYYY-MM-DD HH:mm:SS')
|
||
payload['unix'] = arrow.utcnow().timestamp
|
||
|
||
resp.body = json.dumps(payload)
|
||
resp.status = falcon.HTTP_200
|
||
```
|
||
|
||
Vamos passar por esse trecho. Definimos uma classe `Timestamp` e definimos um método de classe chamado `on_get` - essa função informa ao Falcon que quando uma solicitação `GET` é emitida para um nó de extremidade desse recurso, execute a função `on_get` e forneça os objetos request e response como parâmetros. Depois disso, é fácil navegar - criamos um dicionário vazio, o preenchemos com os timestamps UTC e UNIX atuais, o convertemos em JSON e o anexamos ao objeto de resposta.
|
||
|
||
Muito simples, certo? Mas infelizmente isso não é tudo. Agora precisamos criar um servidor Falcon e conectar a classe de recursos que acabamos de definir para um terminal real.
|
||
|
||
`$ touch app.py`
|
||
|
||
Agora, adicione o código abaixo:
|
||
|
||
```python
|
||
import falcon
|
||
|
||
from timestamp import Timestamp
|
||
|
||
api = application = falcon.API()
|
||
|
||
timestamp = Timestamp()
|
||
|
||
api.add_route('/timestamp', timestamp)
|
||
```
|
||
|
||
Aqui, definimos uma API do Falcon e inicializamos uma instância da classe de recursos que criamos anteriormente. Em seguida, conectamos o terminal `/timestamp` à instância da classe - e agora estamos prontos! Para testar essa API, instale o `gunicorn` ( `pip install gunicorn` ) e execute o `gunicorn app` . Use o Postman ou o `cURL` simples para testar isso:
|
||
```
|
||
$ curl http://localhost:8000/timestamp
|
||
{"utc": "2017-10-20 06:03:14", "unix": 1508479437}
|
||
```
|
||
|
||
E isso faz!
|
||
|
||
## Se movendo
|
||
|
||
Uma vez que você conhece o Falcon, compor poderosas APIs RESTful que interagem com bancos de dados ou filas de mensagens é muito fácil. Confira os [documentos](https://falcon.readthedocs.io/en/stable/index.html) do [Falcon](https://falcon.readthedocs.io/en/stable/index.html) , assim como o PyPI para módulos interessantes do Falcon que continuam aparecendo. |