Skip to content

Latest commit

 

History

History
283 lines (208 loc) · 9.33 KB

quickstart.rst

File metadata and controls

283 lines (208 loc) · 9.33 KB
Raw

Getting started

Using hrefs with FastAPI

Setting up the application

To make the hrefs library work with FastAPI, hrefs.starlette.HrefMiddleware needs to be included in the middleware stack.

from fastapi import FastAPI from fastapi.middleware import Middleware from hrefs.starlette import HrefMiddleware

app = FastAPI(middleware=[Middleware(HrefMiddleware)])

Defining a referrable model

from fastapi import HTTPException from hrefs import BaseReferrableModel

class Book(BaseReferrableModel):

id: int title: str

class Config:

details_view = "get_book"

books = {

1: Book(id=1, title="Basic hrefs"), 2: Book(id=2, title="Advanced hrefs"), 3: Book(id=3, title="Masterful hrefs"),

}

@app.get("/books/{id}") def get_book(id: int) -> Book: book = books.get(id) if not book: raise HTTPException(status_code=404, detail="Book not found") return book

To make a model target for hyperlinks, it needs to:

  • Inherit from hrefs.BaseReferrableModel.
  • Have a configuration called details_view naming the route that returns the representation of the model. The URLs will be built by reversing that route, using the model primary key as parameter.

Note

Pydantic v2 deprecates config classes and uses config dicts as the new configuration mechanism. See pydantic_v2 for more information how this affects hrefs.

In the above example Book.id is the primary key. The primary key usually corresponds to a database primary key, but it's by no means a requirement. By default, the primary key is the id field but can be configured. See configure_key for details.

The primary key name typically appears as a path parameter in the route, but this isn't required either. Keys can be converted to and from both path and query parameters. Keys omitted from the path are assumed to be query parameters.

Note

If the way to set up the route doesn't look familiar, refer to the FastAPI documentation. The route name defaults to the name of the handler function, but can also be defined explicitly using the name keyword argument in the @app.get() decorator.

Note

Routes mounted via sub-applications are also supported. The library relies on the Starlette reverse URL lookup to convert keys to URLs, so don't forget to use the {prefix}:{name} style to refer to the route in case you use named mounts.

Defining a relationship to the referrable model

from fastapi import Response from hrefs import Href from pydantic import parse_obj_as

class Library(BaseReferrableModel):

id: int books: list[Href[Book]]

class Config:

details_view = "get_library"

libraries: dict[int, Library] = {}

@app.get("/libraries/{id}") def get_library(id: int) -> Library: library = libraries.get(id) if not library: raise HTTPException(status_code=404, detail="Library not found") return library

@app.post("/libraries") def post_library(library: Library): if any(book.key not in books for book in library.books): raise HTTPException( status_code=400, detail="Trying to add a nonexistent book to library" ) libraries[library.id] = library return Response( status_code=201, headers={"Location": str(parse_obj_as(Href[Library], library).url)}, )

The annotated type Href[Book] is used to declare a hyperlink to Book.

The hrefs.Href class integrates to pydantic. When parsing the books field, the following values can automatically be converted to hyperlinks:

  • Another hrefs.Href instance.
  • An instance of the referred object type (in this case Book).
  • Any value convertible to the type of the id field (in this case int).
  • A URL that can be matched to the route named in the details_view of the referred object type (in this case "get_library").

When pydantic serializes hrefs.Href objects to JSON, they are serialized as URLs.

>>> from fastapi.testclient import TestClient >>> client = TestClient(app) >>> response = client.post( ... "/libraries", ... json={ ... "id": 1, ... "books": [ ... "http://testserver/books/1", ... "http://testserver/books/2", ... "http://testserver/books/3", ... ] ... } ... ) >>> response.headers["Location"] 'http://testserver/libraries/1' >>> response = client.get("http://testserver/libraries/1") >>> response.json() {'id': 1, 'books': ['http://testserver/books/1', 'http://testserver/books/2', 'http://testserver/books/3']}

A full working example

The tests/ folder contains a minimal toy application demonstrating how the hrefs library is used. It is an expanded version of the small application used as an example in this chapter that also demonstrates advanced. The code is reproduced here for convenience:

../tests/app.py

You can run the test application on your favorite ASGI server:

$ uvicorn tests.app:app
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Then use your favorite HTTP client and start creating libraries. You can use either IDs or URLs to refer to the books in the second POST request --- the library knows how to parse either!

$ http POST localhost:8000/books title='My first book'
HTTP/1.1 201 Created
Transfer-Encoding: chunked
location: http://localhost:8000/books/fb69a5d5-b956-4189-8e3e-89f001815bec
server: uvicorn


$ http POST localhost:8000/libraries books:='["http://localhost:8000/books/fb69a5d5-b956-4189-8e3e-89f001815bec"]'
HTTP/1.1 201 Created
Transfer-Encoding: chunked
location: http://localhost:8000/libraries/50c224ff-c9f4-4186-8a05-4999f522ea67
server: uvicorn


$ http GET http://localhost:8000/libraries/50c224ff-c9f4-4186-8a05-4999f522ea67
HTTP/1.1 200 OK
content-length: 50
content-type: application/json
server: uvicorn

{
    "books": [
        "http://localhost:8000/books/fb69a5d5-b956-4189-8e3e-89f001815bec"
    ],
    "self": "http://localhost:8000/libraries/50c224ff-c9f4-4186-8a05-4999f522ea67"
}

Using hrefs with pydantic v2

Pydantic v2 introduces numerous backward incompatible changes and deprecates many classes and functions used in v1. Unless otherwise mentioned, this guide uses v1 style, but it is straightforward to use the corresponding v2 classes and functions.

One notable change in pydantic v2 is using model config instead of config classes. Using v2 style, the definition of Book from the starlette_models section becomes:

from hrefs import BaseReferrableModel, HrefsConfigDict

class Book(BaseReferrableModel):
    model_config = HrefsConfigDict(details_view="get_book")

    id: int
    title: str

Note that we use hrefs.HrefsConfigDict instead of pydantic.ConfigDict. The former is a subtype of the latter that includes details_view. Using it ensures that auto-completion and type checking tools work as intended. If you don't care about type based tooling, using pydantic.ConfigDict or native dict is just as good.

Using hrefs with Starlette

While the library was written with FastAPI in mind, the integration doesn't depend on FastAPI, only pydantic and Starlette. You can perfectly well write Starlette apps containing hrefs. You just need to ensure that:

  • For each subclass of hrefs.BaseReferrableModel there is a named route matching the details_view configuration.
  • hrefs.starlette.HrefMiddleware is added to the middleware stack.
  • In the responses, the pydantic models containing references are explicitly serialized using the model.json() method (or model.model_dump_json() in pydantic v2).

Writing a custom integration

The hrefs library works out of the box with Starlette and FastAPI, but can be integrated to work with other web frameworks too.

The hrefs.Href class can refer to any type implementing the hrefs.Referrable abstract base class. If you plan to take advantage of pydantic type annotations and want metaclass magic to take care of most of the heavy lifting, hrefs.BaseReferrableModel is the best starting point.

See custom_web_framework_api for the API that new web framework integrations need to implement.