papers/hanzo-api-gateway/sections/02-api-design-principles.tex

\section{API Design Principles}


\subsection{Resource Model}

The Hanzo API exposes e-commerce entities as resources:

\begin{definition}[Commerce Resource]
A resource $R$ is a tuple $(type, id, attributes, relationships)$ where:
\begin{itemize}
    \item $type \in \{Product, Order, Customer, Cart, Collection, Discount\}$
    \item $id$: globally unique identifier
    \item $attributes$: key-value properties
    \item $relationships$: references to related resources
\end{itemize}
\end{definition}

\subsection{REST Interface}

REST endpoints follow a consistent pattern:

\begin{lstlisting}[caption=REST Endpoint Structure]
# Collection endpoints
GET    /v1/{resource}           # List resources
POST   /v1/{resource}           # Create resource

# Instance endpoints
GET    /v1/{resource}/{id}      # Read resource
PUT    /v1/{resource}/{id}      # Replace resource
PATCH  /v1/{resource}/{id}      # Update resource
DELETE /v1/{resource}/{id}      # Delete resource

# Nested resources
GET    /v1/{resource}/{id}/{nested}
\end{lstlisting}

\subsubsection{Query Parameters}

List endpoints support filtering, sorting, and pagination:

\begin{equation}
query = \{fields, filter, sort, page, limit\}
\end{equation}

\begin{lstlisting}[caption=REST Query Example]
GET /v1/products?fields=id,name,price
    &filter[category]=electronics
    &filter[price.gte]=100
    &sort=-created_at
    &page=2&limit=50
\end{lstlisting}

\subsection{GraphQL Interface}

GraphQL provides flexible querying:

\begin{lstlisting}[caption=GraphQL Schema Excerpt]
type Product {
  id: ID!
  name: String!
  description: String
  price: Money!
  variants: [Variant!]!
  collections: [Collection!]!
  inventory: Inventory!
}

type Query {
  product(id: ID!): Product
  products(
    filter: ProductFilter
    first: Int
    after: String
  ): ProductConnection!
}

type Mutation {
  createProduct(input: ProductInput!): Product!
  updateProduct(id: ID!, input: ProductInput!): Product!
}
\end{lstlisting}

\subsubsection{Query Complexity Analysis}

To prevent resource exhaustion, we analyze query complexity:

\begin{definition}[Query Complexity]
For GraphQL query $Q$, complexity is:
\begin{equation}
complexity(Q) = \sum_{f \in fields(Q)} cost(f) \cdot multiplier(f)
\end{equation}
where $cost(f)$ is the base cost of field $f$ and $multiplier(f)$ accounts for list cardinality.
\end{definition}

\begin{algorithm}
\caption{GraphQL Complexity Analysis}
\begin{algorithmic}[1]
\Function{ComputeComplexity}{$node$, $multiplier$}
    \State $total \gets 0$
    \For{$field \in node.selections$}
        \State $cost \gets baseCost(field.name)$
        \State $mult \gets multiplier$
        \If{$isList(field.type)$}
            \State $limit \gets getLimit(field.arguments)$
            \State $mult \gets mult \times \min(limit, maxLimit)$
        \EndIf
        \State $total \gets total + cost \times mult$
        \If{$hasSelections(field)$}
            \State $total \gets total +$ \Call{ComputeComplexity}{$field$, $mult$}
        \EndIf
    \EndFor
    \State \Return $total$
\EndFunction
\end{algorithmic}
\end{algorithm}

Queries exceeding complexity threshold $\theta_{max} = 10,000$ are rejected.