FrappeAPI

Better APIs for Frappe!

⚠️ Alert: Beta Version This project is currently in beta. Expect changes and improvements as we work towards a stable release.

Why?

The goal is to build a better API framework for Frappe.

Roadmap

Frappe Versions

• Frappe V14 support
• Frappe V15 support

Methods

• Implement app.get(...) method.
• Implement app.post(...) method.
• Implement app.put(...) method.
• Implement app.patch(...) method
• Implement app.delete(...) method

Query Parameter Features

• Automatic query parameter parsing/conversion based on type hints.
• Required query parameters needy: str.
• Required query parameters with Ellipsis .... See Pydantic Required Fields and FastAPI Required with Ellipsis.
• Optional query parameters with default values skip: int = 0.
• Optional query parameters without default values limit: Union[int, None] = None.
• Enum support for query parameters path parameters - predefined values.
• Boolean query parameters is_admin: bool = False. see Pydantic's Boolean type.
• List query parameters (i.e. a query parameter q that can appear multiple times in the URL, e.g. ?q=foo&q=bar)
• Aliases for query parameters. q: str = Query(alias="query")
• Query parameters as Pydantic model. filters: Filter. See Query Parameter Models
• Automatic Documentation generation for query parameters.

Body Parameter Features

• Body parameter as Pydantic model. item: Item
• Multiple body parameters. item: Item, user: User, resulting in {"item": {"name": "foo"}, "user": {"name": "bar"}}
• Singular values in body, defined as Body(). name: str = Body() so that to not conflict with query parameters.
• Special embed Body parameter. See Embed a single body parameter
• Nested Models for body parameters.
• Automatic body parameter parsing/conversion based on type hints.

Header Parameters

• Support header parameters like FastAPI did. See Header Parameters
• Header parameters as Pydantic model. See Header Parameter Models
• Duplicate header parameters.
• Ability to forbid extra headers. model_config={"extra": "forbid"}

Cookie Parameters

• Support cookie parameters like FastAPI did.

Form Data

• Define form field as Form(). name: str = Form().
• Multiple form fields. name: str = Form(), age: int = Form()
• Form data as Pydantic model. data: Data
• Ability to forbid extra form fields. model_config={"extra": "forbid"}

File Uploads

• Define file upload field as File(). file: Annotated[bytes, File()], FrappeAPI will read the file for you and you will receive the contents as bytes with file-like interface. This means that the whole contents will be stored in memory. This will work well for small files.
• UploadFile for large files. file: UploadFile. Uses tempfile.SpooledTemporaryFile to store the file contents in memory or disk depending on the size. You get a file-like interface with the file contents streamed from the client to the server. UploadFile is FastAPI's, it supports async file handling, but FrappeAPI does not yet support async APIs, fortunately, UploadFile has file attribute to access the raw standard Python file (blocking, not async), useful and needed for non-async code.
• Optional file upload field. file: Annotated[bytes | None, File()] = None
• Optional UploadFile field. file: UploadFile | None = None
• Multiple file upload fields. files: Annotated[list[bytes], File()]
• Multiple UploadFile fields. files: list[UploadFile]

Handling Errors

• HTTPException
• RequestValidationError
• ResponseValidationError
• Register custom exception handlers. See Add custom headers
• Override default exception handlers.
• Maintain Frappe Transaction Management.

Response Models

• Method response_model parameter to define response model as Pydantic model. response_model=Model, response_model=list[Model] ...etc
• Response model as return type with standard type hints or Pydantic model. -> Model, -> list[Model]...etc
• Limit and filter the output data to what is defined in the return type.
• response_model parameter takes precedence over return type if both are provided.

Additional information and validation fields

• String validations, min_length, max_length, pattern.
• Numeric validations, gt, ge, lt, le.
• Metadata, title, description, deprecated.
• others, include_in_schema.

Rate Limiting

• Support for rate limiting.

Dependencies

• Support for dependencies.

Middleware

• Support for middleware.

Miscellaneous

• Debugging capabilities.

Related Frappe PRs and Issues

• PR #23135: Introducing type hints for API functions.
• PR #22300: Enhancing frappe.whitelist() functionality.
• PR #19029: Efforts to improve type safety in Frappe.
• Issue #14905: Discussion on improving API documentation.