Merge pull request #2 from flusflas/feature/form-urlencoded-support

Adds support for request payloads with `application/x-www-form-urlencoded` content type, and improves handling of
structured content types.

Author: flusflas

CHANGELOG.md

@@ -5,9 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0](https://github.com/flusflas/apier/tree/v0.3.0) (2025-07-31)
+
+This release adds support for request payloads with
+`application/x-www-form-urlencoded` content type, and improves handling of
+structured content types such as `application/json-patch+json`.
+
+### Added
+
+- Handle request content types with structured syntax suffixes.
+- Support for `application/x-www-form-urlencoded` request payloads.
+
 ## [0.2.0](https://github.com/flusflas/apier/tree/v0.2.0) (2025-07-24)
 
-This release adds support for multipart requests, binary responses, improved request handling, and includes various fixes and minor enhancements.
+This release adds support for multipart requests, binary responses, improved
+request handling, and includes various fixes and minor enhancements.
 
 ### Added
 

apier/templates/python_tree/base/internal/content_type.py

@@ -2,7 +2,7 @@
 import mimetypes
 from dataclasses import dataclass, field
 from io import IOBase
-from typing import Any, Optional
+from typing import Any, Optional, Union
 from urllib.parse import parse_qsl
 
 import xmltodict
@@ -109,7 +109,7 @@ class ContentTypeValidationResult:
     type: str = ""  # The request's Content-Type, indicating the data format
     data: Any = None
     files: Optional[dict] = None
-    json: Optional[dict] = None
+    json: Optional[Union[dict, list]] = None
     headers: CaseInsensitiveDict = field(default_factory=dict)
 
 
@@ -124,6 +124,33 @@ def to_plain_text(obj) -> ContentTypeValidationResult:
     )
 
 
+def to_form_urlencoded(obj) -> ContentTypeValidationResult:
+    """
+    Returns the form-urlencoded representation of the given object.
+    Raises an exception if the object cannot be serialized to a valid
+    application/x-www-form-urlencoded format.
+    """
+    result = ContentTypeValidationResult(
+        type="application/x-www-form-urlencoded",
+        headers=CaseInsensitiveDict(
+            {"Content-Type": "application/x-www-form-urlencoded"}
+        ),
+    )
+
+    if isinstance(obj, (str, bytes)):
+        result.data = str(obj)
+    elif isinstance(obj, dict):
+        result.data = obj
+    elif isinstance(obj, APIBaseModel):
+        result.data = json.loads(obj.json(by_alias=True))
+    else:
+        raise ValueError(
+            f'Value type "{type(obj).__name__}" cannot be converted to form-urlencoded'
+        )
+
+    return result
+
+
 def to_json(obj) -> ContentTypeValidationResult:
     """
     Returns the JSON representation of the given object.
@@ -225,6 +252,7 @@ def to_multipart(obj) -> ContentTypeValidationResult:
 
 
 SUPPORTED_REQUEST_CONTENT_TYPES = {
+    "application/x-www-form-urlencoded": to_form_urlencoded,
     "application/json": to_json,
     "application/xml": to_xml,
     "text/plain": to_plain_text,

apier/templates/python_tree/base/internal/resource.py

@@ -399,6 +399,12 @@ def _validate_request_payload(
                     try:
                         result = conv_func(body)
 
+                        # If the content types are not an exact match, update the info
+                        # (e.g. application/json to application/json-patch+json)
+                        if not content_types_match(content_type, ct):
+                            result.type = content_type
+                            result.headers["Content-Type"] = content_type
+
                         # Keep the headers from the request
                         if headers:
                             result.headers.update(headers)

apier/templates/python_tree/security.py

@@ -31,8 +31,7 @@ def parse_security_schemes(definition: Definition) -> list[str]:
                 else:
                     warnings.warn(
                         f"Security scheme '{name}' has an unsupported OAuth2 "
-                        f"flow type ({flow_name}) schema type '{scheme_type}' "
-                        f"and will be ignored"
+                        f"flow type '{flow_name}' and will be ignored"
                     )
                     continue
 

apier/templates/python_tree/templates/api.jinja

@@ -1,5 +1,5 @@
-import json
 from typing import Union
+from urllib.parse import urljoin
 
 import requests
 from pydantic import BaseModel
@@ -39,7 +39,7 @@ class API(
         if not host.startswith("http://") and not host.startswith("https://"):
             host = "https://" + host
 
-        self.host = host
+        self.host = host.rstrip("/")
         self._verify = verify
         self.headers = {}
         self._raise_errors = {{ raise_errors }}
@@ -110,15 +110,16 @@ class API(
 
         headers.update(self.headers)
 
+        # If the payload is a pydantic model, handle it as JSON
         if isinstance(data, BaseModel):
-            data = data.json(by_alias=True)
+            json = data.json(by_alias=True)
         if isinstance(json, BaseModel):
             json = json.json(by_alias=True)
 
         if url.lower().startswith("http://") or url.lower().startswith("https://"):
             url = url
         else:
-            url = self.host + url
+            url = urljoin(self.host, url)
 
         req = requests.Request(
             method, url, params=params, headers=headers, data=data, json=json

docs/templates/python_tree.md

@@ -277,5 +277,6 @@ In the example above, the `stream=True` parameter is used to enable streaming of
 ## ⚠️ Limitations
 
 - 🧬 The `python-tree` template is best suited for APIs that have a clear hierarchical structure. It may not be the best choice for APIs with flat or complex endpoint structures, where a different template design might be more appropriate.
-- 💾 The `python-tree` template supports text, JSON, XML, and multipart payloads for requests. Responses can handle text, JSON, XML, and binary data payloads. Other payload types have not been tested and therefore may not work as expected (or may not work at all).
+- 💾 **Request payloads**: This template supports request payloads with content types such as `text/plain`, `application/json`, `application/xml`, `multipart/form-data`, `application/x-www-form-urlencoded`, and types using structured syntax suffixes like `application/json-patch+json`. Other content types are untested and may not be supported.
+- 📦 **Response payloads**: Supports response content types like `text/plain`, `application/json`, `application/xml`, and binary data.
 - 🧭 Strategies requiring dynamic evaluation of runtime expressions, such as page or offset pagination, are not yet supported.