AgenticAPI’s action-oriented design introduces custom HTTP verbs (e.g., SUMMARIZE, FETCH) to support AI agents, but it ensures seamless integration with traditional RESTful clients by aliasing these verbs to standard HTTP methods like POST. This compatibility allows existing systems to interact with AgenticAPI without requiring changes to client logic, enabling a smooth transition to action-oriented APIs. This document explains how to alias REST endpoints to ACTION verbs and provides an example using FastAPI middleware.

How REST Compatibility Works #

AgenticAPI uses middleware to map standard HTTP methods (e.g., POST, GET) to custom verbs, ensuring that requests to REST endpoints (e.g., POST /document) are routed to their corresponding action verbs (e.g., SUMMARIZE /document). This aliasing is documented in OpenAPI schemas with the x-alias-for extension, allowing both agentic and traditional clients to coexist.

Key features include:

• Transparent Routing: REST requests are automatically redirected to action verb handlers.
• OpenAPI Documentation: Extensions clarify mappings for developer clarity.
• Backward Compatibility: Existing REST clients continue to function without modification.

Example: Aliasing POST to SUMMARIZE #

The following FastAPI middleware aliases a POST /document request to the SUMMARIZE verb, enabling REST clients to trigger summarization.

from fastapi import FastAPI, Request, HTTPException
from pydantic import BaseModel
import logging

app = FastAPI()
logger = logging.getLogger(__name__)

class SummarizeQuery(BaseModel):
    document_id: str
    format: str = "text"
    max_words: int = 50
    style: str = "neutral"
    output_format: str = "json"

async def custom_method_middleware(request: Request, call_next):
    method = request.method.upper()
    path = request.url.path
    logger.info(f"Request received: Method={method}, Path={path}")
    
    if path == "/document" and method == "POST":
        # Alias POST /document to SUMMARIZE /document
        request.scope["method"] = "SUMMARIZE"
        logger.info("Processing POST /document as SUMMARIZE")
    
    response = await call_next(request)
    return response

app.middleware("http")(custom_method_middleware)

@app.api_route("/document", methods=["SUMMARIZE"], openapi_extra={"x-action": "summarize", "x-category": "compute"})
async def summarize_document(query: SummarizeQuery):
    # Simulate summarization
    return {
        "result": {
            "summary": "Report highlights key trends.",
            "title": "Report"
        },
        "used_fallback": False
    }

@app.post("/document", openapi_extra={"x-alias-for": "SUMMARIZE /document"})
async def document_post(query: SummarizeQuery):
    # Redirect to SUMMARIZE handler
    return await summarize_document(query)

REST Request (POST):

curl -X POST http://localhost:8000/document -H "Content-Type: application/json" -d '{
  "document_id": "doc_001",
  "format": "text",
  "max_words": 20,
  "style": "neutral",
  "output_format": "json"
}'

Action Verb Request (SUMMARIZE):

curl -X SUMMARIZE http://localhost:8000/document -H "Content-Type: application/json" -d '{
  "document_id": "doc_001",
  "format": "text",
  "max_words": 20,
  "style": "neutral",
  "output_format": "json"
}'

Response (Same for Both):

{
  "result": {
    "summary": "Report highlights key trends.",
    "title": "Report"
  },
  "used_fallback": false
}

• Middleware: Redirects POST /document to the SUMMARIZE handler by modifying the request method.
• OpenAPI Extensions: x-alias-for documents the mapping.
• Compatibility: Both REST and agentic clients receive identical responses.

Best Practices #

• Document Aliases: Use x-alias-for in OpenAPI schemas to clarify mappings.
• Maintain Consistency: Ensure REST and action verb endpoints share the same payload schema.
• Test Both Paths: Verify REST and action verb requests produce identical results.
• Plan for Deprecation: Gradually transition clients to action verbs, maintaining REST aliases.

Next Steps #

• Explore AI Agent Integration for agent connectivity.
• Learn about Security Best Practices for protecting endpoints.
• Try Chaining Actions to combine verbs.