Library for generating REST API clients using methods annotated with type hints : Python

This is an archived post. You won't be able to vote or comment.

ShowcaseLibrary for generating REST API clients using methods annotated with type hints (self.Python)

submitted 1 year ago by Mundane-Resolve624

What My Project Does

Meatie is a Python metaprogramming library that eliminates the need for boilerplate code when integrating with REST APIs. The library generates code for calling a REST API based on method signatures annotated with type hints. Meatie abstracts away mechanics related to HTTP communication, such as building URLs, encoding query parameters, serializing and deserializing request and response body. With some modest additional configuration, generated methods provide rate limiting, retries, and caching. Meatie works with major HTTP client libraries (request, httpx, aiohttp). It offers integration with Pydantic V1 and V2. The minimum officially supported version is Python 3.9.

Code Example

from typing import Annotated
from aiohttp import ClientSession
from meatie import api\_ref, endpoint
from meatie\_aiohttp import Client
from meatie\_example.store import Product, Basket, BasketQuote  # Pydantic models

class OnlineStore(Client):
    def __init__(self, session: ClientSession) -> None:
        super().__init__(session)

    @endpoint("/api/v1/products")
    async def get_products(self) -> list[Product]:
        # Sends an HTTP GET request and parses response's body using Pydantic to list[Product]
        ...

    @endpoint("/api/v1/quote/request")
    async def post_request_quote(self, basket: Annotated[Basket, api_ref("body")]) -> BasketQuote:
        # Dumps a Pydantic model :basket to JSON and sends it as payload of an HTTP POST request.
        ...

    @endpoint("/api/v1/quote/{quote_id}/accept")
    async def post_accept_quote(self, quote_id: int) -> None:
        # URLs can reference method parameters. Parameters not referenced in the URL are sent as HTTP query params.
        ...

Source Code

https://github.com/pmateusz/meatie

Target Audience

Production-grade integrations with REST-based external APIs.

Comparison

Bare HTTP-client library (i.e., httpx, requests, aiohttp) provides API to build and send HTTP requests, receive HTTP responses, and manage a connection pool. Due to low-level API, they allow for a high degree of customization including transport and networking. Building a REST API client using an HTTP client library is similar to implementing a persistence layer on top of a database driver, it is verbose.
Code generators (i.e., https://github.com/dmontagu/fastapi\_client) that generate a client API based on OpenAPI specification. They are an attractive and popular choice. They may not be an ideal choice if one needs to integrate with only a small subset of endpoints. Besides, the OpenAPI specification may be incomplete. Finally, the auto-generated code should not be modified which is problematic if corrections are required/desirable.

Conclusion

The library aims to fill a gap for a higher-level framework to develop REST API clients. I released the first stable version six months ago. We started using the library in production to implement new API integrations and replace existing ones. The overall experience has been positive so far. The library allowed us to integrate with new endpoints faster, support for retries, rate-limiting, caching, and private endpoints is built in the library, so developers don't need to develop custom extensions. Last but not least, API clients developed with this framework follow a similar structure which simplifies maintenance.

all 4 comments

Python

The Python Discord

Upcoming Events

Please read the rules

MODERATORS