mirror of
https://github.com/kennethreitz/responder.git
synced 2026-06-05 23:00:17 +00:00
94 lines
2.6 KiB
ReStructuredText
94 lines
2.6 KiB
ReStructuredText
Quick Start
|
|
===========
|
|
|
|
This section of the documentation exists to provide an introduction to the Responder interface,
|
|
as well as educate the user on basic functionality.
|
|
|
|
|
|
Declare a Web Service
|
|
---------------------
|
|
|
|
The first thing you need to do is declare a web service::
|
|
|
|
import responder
|
|
|
|
api = responder.API()
|
|
|
|
Hello World!
|
|
------------
|
|
|
|
Then, you can add a view / route to it.
|
|
|
|
Here, we'll make the root URL say "hello world!"::
|
|
|
|
@api.route("/")
|
|
def hello_world(req, resp):
|
|
resp.text = "hello, world!"
|
|
|
|
Run the Server
|
|
--------------
|
|
|
|
Next, we can run our web service easily, with ``api.run()``::
|
|
|
|
api.run()
|
|
|
|
This will spin up a production web server on port ``5042``, ready for incoming HTTP requests.
|
|
|
|
Note: you can pass ``port=5000`` if you want to customize the port. The ``PORT`` environment variable for established web service providers (e.g. Heroku) will automatically be honored.
|
|
|
|
|
|
Accept Route Arguments
|
|
----------------------
|
|
|
|
If you want dynamic URLs, you can use Python's familiar *f-string syntax* to declare variables in your routes::
|
|
|
|
@api.route("/hello/{who}")
|
|
def hello_to(req, resp, *, who):
|
|
resp.text = f"hello, {who}!"
|
|
|
|
A ``GET`` request to ``/hello/brettcannon`` will result in a response of ``hello, brettcannon!``.
|
|
|
|
Returning JSON / YAML
|
|
---------------------
|
|
|
|
If you want your API to send back JSON, simply set the ``resp.media`` property to a JSON-serializable Python object::
|
|
|
|
|
|
@api.route("/hello/{who}/json")
|
|
def hello_to(req, resp, *, who):
|
|
resp.media = {"hello", who}
|
|
|
|
A ``GET`` request to ``/hello/guido/json`` will result in a response of ``{'hello': 'guido'}``.
|
|
|
|
If the client requests YAML instead (with a header of ``Accept: application/x-yaml``), YAML will be sent.
|
|
|
|
|
|
Receiving Data & Background Tasks
|
|
---------------------------------
|
|
|
|
If you're expecting *form-encoded* data, on the server, you need to declare your view as async.
|
|
|
|
Here, we'll process our data in the background, while responding immediately to the client::
|
|
|
|
import time
|
|
|
|
@api.route("/incoming")
|
|
async def receive_incoming(req, resp):
|
|
|
|
@api.background.task
|
|
def process_data(data):
|
|
# Just sleep for three seconds, as a demo.
|
|
time.sleep(3)
|
|
|
|
|
|
# Parse the incoming data as form-encoded.
|
|
data = await resp.media('form') # ``'json'`` and ``yaml`` formats are also supported.
|
|
|
|
# Process the data (in the background).
|
|
process_data(data)
|
|
|
|
# Immediately respond that upload was successful.
|
|
resp.media = {'success': True}
|
|
|
|
A ``POST`` request to ``/incoming`` will result in an immediate response of ``{'success': true}``.
|