Real-World Examples

Complete Working Examples

Learn from real-world API patterns. Each example is a complete, valid OpenAPI spec you can import directly into Tigrister.

What You'll Learn
  • • E-Commerce API - CRUD operations, auth, pagination
  • • Payment API - Webhooks, callbacks, idempotency
  • • Social API - OAuth2, nested resources, media
  • • Microservices - External refs, versioning

E-Commerce API

CRUD + Auth

A typical e-commerce API with products, orders, and user authentication. Demonstrates standard REST patterns.

Full Spec
openapi: '3.0.3'
info:
title: E-Commerce API
version: '1.0.0'
description: Product catalog and order management
servers:
- url: https://api.shop.example.com/v1
description: Production
- url: https://sandbox.shop.example.com/v1
description: Sandbox
tags:
- name: Products
description: Product catalog
- name: Orders
description: Order management
- name: Auth
description: Authentication
paths:
# Products
/products:
get:
tags: [Products]
summary: List products
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 100
- name: category
in: query
schema:
type: string
responses:
'200':
description: Product list
content:
application/json:
schema:
$ref: '#/components/schemas/ProductList'
post:
tags: [Products]
summary: Create product
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProductCreate'
responses:
'201':
description: Product created
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
'401':
$ref: '#/components/responses/Unauthorized'
/products/{id}:
get:
tags: [Products]
summary: Get product
parameters:
- $ref: '#/components/parameters/ProductId'
responses:
'200':
description: Product details
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
'404':
$ref: '#/components/responses/NotFound'
# Orders
/orders:
post:
tags: [Orders]
summary: Create order
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCreate'
responses:
'201':
description: Order created
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
parameters:
ProductId:
name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Product:
type: object
required: [id, name, price]
properties:
id:
type: string
format: uuid
name:
type: string
example: "Wireless Mouse"
price:
type: number
format: double
example: 29.99
category:
type: string
stock:
type: integer
ProductCreate:
type: object
required: [name, price]
properties:
name:
type: string
price:
type: number
category:
type: string
ProductList:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Product'
total:
type: integer
page:
type: integer
limit:
type: integer
OrderCreate:
type: object
required: [items]
properties:
items:
type: array
items:
type: object
properties:
productId:
type: string
quantity:
type: integer
Order:
type: object
properties:
id:
type: string
status:
type: string
enum: [pending, paid, shipped, delivered]
total:
type: number
Error:
type: object
properties:
code:
type: string
message:
type: string

Pattern: Pagination

page/limit params with total count in response

Pattern: Reusable Components

$ref for parameters, responses, schemas

Pattern: Bearer Auth

JWT token for protected endpoints

Payment API

Webhooks3.1

A payment processing API with webhooks for async notifications. Uses OpenAPI 3.1 for top-level webhooks.

Key Sections
openapi: '3.1.0'
info:
title: Payment API
version: '2.0.0'
paths:
/payments:
post:
summary: Create payment
operationId: createPayment
parameters:
- name: Idempotency-Key
in: header
required: true
description: Unique key for idempotent requests
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequest'
responses:
'201':
description: Payment initiated
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
# Callback for async payment result
callbacks:
paymentComplete:
'{$request.body#/webhookUrl}':
post:
summary: Payment result callback
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentEvent'
responses:
'200':
description: Callback received
# Top-level webhooks (3.1 feature)
webhooks:
paymentUpdated:
post:
summary: Payment status changed
description: Sent when payment transitions to a new status
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentEvent'
responses:
'200':
description: Webhook acknowledged
refundCompleted:
post:
summary: Refund processed
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RefundEvent'
responses:
'200':
description: Acknowledged
components:
schemas:
PaymentRequest:
type: object
required: [amount, currency, webhookUrl]
properties:
amount:
type: integer
description: Amount in cents
currency:
type: string
enum: [USD, EUR, GBP]
webhookUrl:
type: string
format: uri
PaymentEvent:
type: object
properties:
event:
type: string
enum: [payment.succeeded, payment.failed]
paymentId:
type: string
timestamp:
type: string
format: date-time

Pattern: Idempotency

Idempotency-Key header prevents duplicate charges

Pattern: Async Webhooks

Top-level webhooks for payment status updates

Social API

OAuth2

A social media API with OAuth2 authorization code flow, nested resources, and media upload support.

OAuth2 + Nested Resources
openapi: '3.0.3'
info:
title: Social API
version: '1.0.0'
servers:
- url: https://api.social.example.com
paths:
# Current user
/me:
get:
summary: Get current user profile
security:
- OAuth2:
- profile:read
responses:
'200':
description: User profile
content:
application/json:
schema:
$ref: '#/components/schemas/User'
# Nested: User's posts
/users/{userId}/posts:
get:
summary: Get user's posts
security:
- OAuth2:
- posts:read
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: List of posts
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Post'
# Media upload
/media:
post:
summary: Upload media
security:
- OAuth2:
- media:write
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
alt_text:
type: string
responses:
'201':
description: Media uploaded
content:
application/json:
schema:
$ref: '#/components/schemas/Media'
components:
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://social.example.com/oauth/authorize
tokenUrl: https://social.example.com/oauth/token
refreshUrl: https://social.example.com/oauth/refresh
scopes:
profile:read: Read user profile
profile:write: Update profile
posts:read: Read posts
posts:write: Create/edit posts
media:write: Upload media
schemas:
User:
type: object
properties:
id:
type: string
username:
type: string
displayName:
type: string
avatarUrl:
type: string
format: uri
Post:
type: object
properties:
id:
type: string
content:
type: string
author:
$ref: '#/components/schemas/User'
media:
type: array
items:
$ref: '#/components/schemas/Media'
createdAt:
type: string
format: date-time
Media:
type: object
properties:
id:
type: string
url:
type: string
type:
type: string
enum: [image, video, gif]

Pattern: OAuth2 Scopes

Fine-grained permissions per endpoint

Pattern: Nested Resources

/users/{userId}/posts hierarchy

Pattern: File Upload

multipart/form-data with binary

Microservices API

External RefsVersioning

A microservices architecture with shared schemas via external references and API versioning strategies.

Gateway + Shared Schemas
# api-gateway.yaml - Main Gateway Spec
openapi: '3.0.3'
info:
title: API Gateway
version: '2.1.0'
x-api-version: v2 # Custom version header
servers:
- url: https://api.example.com/{version}
variables:
version:
default: v2
enum: [v1, v2]
paths:
/users:
$ref: './services/user-service.yaml#/paths/~1users'
/orders:
$ref: './services/order-service.yaml#/paths/~1orders'
/products:
$ref: './services/catalog-service.yaml#/paths/~1products'
components:
schemas:
# Shared schemas from common library
Error:
$ref: './shared/common.yaml#/components/schemas/Error'
Pagination:
$ref: './shared/common.yaml#/components/schemas/Pagination'
AuditInfo:
$ref: './shared/common.yaml#/components/schemas/AuditInfo'
securitySchemes:
ServiceAuth:
$ref: './shared/security.yaml#/components/securitySchemes/ServiceAuth'
# ─────────────────────────────────────────
# shared/common.yaml - Shared Schemas
components:
schemas:
Error:
type: object
required: [code, message, traceId]
properties:
code:
type: string
example: ERR_NOT_FOUND
message:
type: string
traceId:
type: string
format: uuid
description: Distributed tracing ID
Pagination:
type: object
properties:
page:
type: integer
limit:
type: integer
total:
type: integer
hasMore:
type: boolean
AuditInfo:
type: object
properties:
createdAt:
type: string
format: date-time
createdBy:
type: string
updatedAt:
type: string
format: date-time

Pattern: External $ref

Shared schemas across services

Pattern: URL Versioning

Server variable for API version

Pattern: Distributed Tracing

traceId in error responses

Try These Examples in Tigrister

All examples on this page are valid OpenAPI specs. Here's how to import and test them:

Import Steps
  1. Copy any example YAML from above
  2. Open Tigrister Designer mode
  3. Switch to Code Editor
  4. Paste the YAML content
  5. Tigrister auto-validates and parses
Test with Try It Out
  1. Switch to Preview tab
  2. Expand any endpoint
  3. Click "Try It Out"
  4. Fill in parameters
  5. Execute and see results

Tip: Use with Real APIs

Replace example.com URLs with real API endpoints to test against actual services. Configure authentication in Area Mode to test protected endpoints.

Common Patterns Quick Reference

Pagination
parameters:
- name: page
in: query
schema: { type: integer, default: 1 }
- name: limit
in: query
schema: { type: integer, max: 100 }
Error Response
Error:
type: object
properties:
code: { type: string }
message: { type: string }
details: { type: array }
Cursor Pagination
parameters:
- name: cursor
in: query
schema: { type: string }
description: Next page cursor
Rate Limit Headers
headers:
X-RateLimit-Limit:
schema: { type: integer }
X-RateLimit-Remaining:
schema: { type: integer }
X-RateLimit-Reset:
schema: { type: integer }
Related Topics
→ Authentication→ Webhooks & Callbacks→ Schema Composition→ External References
ExportingTroubleshooting