Endpoints¶

register¶

An endpoint for registering a user. If you send a GET request to this endpoint, a simple registration form is rendered, where a user can manually sign up.

Hint

You can use a custom template, which matches the look and feel of your application. See the template_path parameter.

Alternatively, you can register a user programatically by sending a POST request to this endpoint (passing in username, email, password and confirm_password parameters as JSON, or as form data).

When registration is successful, the user can be redirected to a login endpoint. The destination can be configured using the redirect_to parameter.

Examples¶

Here’s a Starlette example:

from piccolo_api.register.endpoints import register
from starlette import Starlette

app = Starlette()

app.mount('/register/', register(redirect_to="/login/"))

Here’s a FastAPI example:

from fastapi import FastAPI
from piccolo_api.register.endpoints import register

app = FastAPI()

app.mount('/register/', register(redirect_to="/login/"))

Security¶

The endpoint is fairly simple, and works well for building a quick prototype, or internal application. If it’s being used on the public internet, then extra precautions are required.

Rate limiting¶

One option is to apply rate limiting to this endpoint. This can be done using RateLimitingMiddleware. Modifying the FastAPI example above:

from fastapi import FastAPI
from piccolo_api.rate_limiting.middleware import (
    RateLimitingMiddleware, InMemoryLimitProvider
)
from piccolo_api.register.endpoints import register

app = FastAPI()

app.mount(
    '/register/',
    RateLimitingMiddleware(
        register(redirect_to="/login/"),
        InMemoryLimitProvider(
            timespan=3600,  # 1 hour
            limit=20,
            block_duration=86400  # 24 hours
        )
    )
)

We have used quite aggressive rate limiting here - there is no reason for a user to visit a registration page a large number of times.

CAPTCHA¶

Alternatively, we can easily integrate a CAPTCHA service. Sign up for an account with hCaptcha or reCAPTCHA, and then do the following:

from fastapi import FastAPI
from piccolo_api.register.endpoints import register
from piccolo_api.shared.auth.captcha import hcaptcha, recaptcha_v2

app = FastAPI()

# To use hCaptcha:
app.mount(
    '/register/',
    register(
        redirect_to="/login/",
        captcha=hcaptcha(
            site_key='my-site-key',
            secret_key='my-secret-key',
        )
    )
)

# To use reCAPTCHA:
app.mount(
    '/register/',
    register(
        redirect_to="/login/",
        captcha=recaptcha_v2(
            site_key='my-site-key',
            secret_key='my-secret-key',
        )
    )
)

For a complete example app, see here.

Building your own¶

There is no one-size-fits-all registration solution. You can use this endpoint as a basis for your own solution, which fits the needs of your application. For example, you can add extra registration fields.

Source¶

piccolo_api.register.endpoints.register(auth_table: t.Type[BaseUser] = BaseUser, redirect_to: t.Union[str, URL] = '/login/', template_path: t.Optional[str] = None, user_defaults: t.Optional[t.Dict[str, t.Any]] = None, captcha: t.Optional[Captcha] = None, styles: t.Optional[Styles] = None, read_only: bool = False) → t.Type[RegisterEndpoint][source]¶

An endpoint for register user.

Parameters:

auth_table – Which Table to create the user in. It defaults to BaseUser.
redirect_to – Where to redirect to after successful registration.
template_path – If you want to override the default register HTML template, you can do so by specifying the absolute path to a custom template. For example '/some_directory/register.html'. Refer to the default template at piccolo_api/templates/register.html as a basis for your custom template.
user_defaults –
These values are assigned to the new user. An example use case is setting active = True on each new user, so they can immediately login (not recommended for production, as it’s better to verify their email address first, but OK for a prototype app):
```
register(user_defaults={'active': True})
```
captcha – Integrate a CAPTCHA service, to provide protection against bots. See Captcha.
styles – Modify the appearance of the HTML template using CSS.

Read_only:

If True, the endpoint only responds to GET requests. It’s not commonly needed, except when running demos.