papers/hanzo-sdk-ecosystem/sections/03-openapi-specification.tex

\section{OpenAPI Specification}


\subsection{API Schema}

The Hanzo API is fully described in OpenAPI 3.0:

\begin{lstlisting}[caption=OpenAPI Schema Excerpt]
openapi: 3.0.0
info:
  title: Hanzo Commerce API
  version: 2019-10-01

paths:
  /v1/products:
    get:
      operationId: listProducts
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'

components:
  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id:
          type: string
        name:
          type: string
        price:
          type: integer
          description: Price in cents
        description:
          type: string
          nullable: true
\end{lstlisting}

\subsection{Custom Extensions}

We extend OpenAPI with SDK-specific metadata:

\begin{lstlisting}[caption=SDK Extensions]
x-resource: Product
x-operations:
  - list
  - create
  - retrieve
  - update
  - delete
x-expandable:
  - variants
  - collections
x-idempotent: true
\end{lstlisting}