Share
Embed
How OpenAPI Is Transforming API Client Development
This talk was spoken on COSCUP x Ruby Conf Taiwan 2025
https://coscup.org/2025/en/sessions/XARKVG
4geru
August 09, 2025
Transcript
42 slides
-
How OpenAPI Is Transforming API Client Development From God Class
to Glory: A Real-World Transformation Story Event: COSCUP 2025 Taiwan Date: 2025/08/09-10 1 -
About Me Name: Uchinishi Koichi (@4geru) X (Twitter): @_4geru Github:
@4geru LINE API Expert: 2018 ~ not a LY Corporation member First time to come Taiwan 2 -
Our Journey Today Act I: The Problem 1. The Universal
API Client Struggle: Why API client development is hard 2. The Dark Ages of v1: When "God Class" ruled the kingdom Act II: The Solution 3. The Light: OpenAPI changes everything 4. Revolution in v2: OpenAPI-driven automation and implementation Act III: The Transformation 5. v1 vs v2: The strongest difference - JSON vs Class components 6. Results Achieved: Measurable impact on speed and quality 7. Key Takeaways: Your OpenAPI adventure starts now 3 -
Imagine this scenario: Your team launches a new API feature
on Monday. How long until all your SDKs support it? a) Same day b) Within a week c) "We'll get to it when we can..." d) "What SDKs?" If you answered (c) or (d), this talk is for you! 4 -
1. The Universal API Client Struggle Why API client development
is universally challenging across languages and platforms 5 -
1.1 About LINE API Multi-language SDK support: Python, Ruby, Java,
Node.js, PHP, Go, Flutter... While our case study uses Ruby OpenAPI specifications: https://github.com/line/line-openapi Multiple API domains: Messaging, Authentication, Analytics, and more 6 -
2. The Dark Ages of v1 When "God Class" ruled
the kingdom and manual maintenance hit its limits 7 -
v1 SDK: File structure line-bot-sdk-ruby/ ├── lib/line/bot/v1/ # v1 Implementation
(deprecated) │ ├── client.rb # God Class (50+ deprecated methods) │ ├── httpclient.rb # HTTP client implementation │ ├── event.rb # Event handling base │ ├── api/ │ │ ├── errors.rb # API error definitions │ │ └── version.rb # Version tracking │ └── event/ # Event system (14 types) │ ├── base.rb # Base event class │ ├── message.rb # Message events │ ├── postback.rb # Postback events │ └── ... (11+ event types) 8 -
v1 SDK: client.rb has many functions line-bot-sdk-ruby/ └── lib/line/bot/v1/ #
v1 Implementation (deprecated) └── client.rb # God Class (50+ deprecated methods) ├── .reply_message() # Messaging operations ├── .push_message() ├── .multicast() ├── .broadcast() ├── .get_profile() # User profile operations ├── .create_rich_menu() # Rich menu management ├── .validate_signature() # Webhook validation └── ... (40+ methods) 9 -
The God Class Problems: 1,000+ lines of code in a
single file 50+ methods handling everything from messaging to analytics Hash-based parameters = runtime errors waiting to happen Tight coupling makes testing a nightmare Every API change requires manual code updates Result: Development bottleneck and maintenance burden → Limits of manual maintenance 10 -
3. The Light: OpenAPI Changes Everything How OpenAPI became the
game changer that revolutionized API client development 11 -
What if I told you... You could generate perfect SDKs
in 10+ languages from one file? Your documentation never goes out of sync? Type safety comes for free? API changes propagate instantly to all clients? "Impossible!" you say? Welcome to the OpenAPI revolution! 12 -
Key Benefits of OpenAPI 1/2 Developer Experience Type Safety: Compile-time
error detection prevents runtime failures IDE Support: Full autocompletion and intellisense across all languages Self-Documenting: API structure is immediately clear from generated code Development Speed Automated Code Generation: SDKs generated in minutes, not months Instant Updates: API changes propagate to all SDKs simultaneously Reduced Manual Work: No more hand-crafting request/response objects 13 -
Key Benefits of OpenAPI 2/2 Quality & Consistency Single Source
of Truth: One specification drives all implementations Cross-Language Consistency: Same behavior across Python, Ruby, Java, etc. Validation: Automatic request/response validation built-in Scalability Multi-Language Support: Add new language SDKs effortlessly Team Collaboration: API changes visible to all stakeholders CI/CD Integration: Automated testing and deployment pipelines 14 -
OpenAPI Specification Example paths: /v2/bot/message/reply: post: summary: Send reply message
# ← API description requestBody: required: true # ← Body is mandatory content: application/json: schema: type: object properties: replyToken: type: string # ← String validation messages: type: array # ← Array of messages items: $ref: '#/components/schemas/Message' # ← Type reference Next 15 -
Message Schema: Polymorphic Type System components: schemas: Message: type: object
discriminator: propertyName: type # ← Determines message type mapping: text: '#/components/schemas/TextMessage' # ← Text messages image: '#/components/schemas/ImageMessage' # ← Image messages flex: '#/components/schemas/FlexMessage' # ← Flex messages Next template: '#/components/schemas/TemplateMessage' # ← Template messages properties: type: type: string # ← Message type identifier required: - type # ← Type is mandatory 16 -
LINE's OpenAPI Specification Example components: schemas: FlexMessage: type: object properties:
type: type: string enum: ['flex'] # ← Restricts to 'flex' only altText: type: string # ← Required string property contents: $ref: '#/components/schemas/FlexContainer' # ← References other schema 17 -
OpenAPI Generator: Overview What is OpenAPI Generator? Open-source tool that
generates client SDKs, server stubs, and documentation 50+ language support: Ruby, Python, Java, TypeScript, Go, PHP, and more Community-driven: Thousands of contributors, battle-tested in production How It Works: OpenAPI Spec (YAML) → OpenAPI Generator → Language-specific SDK 18 -
OpenAPI Generator: Setup & Usage Installation: Docker, npm, Homebrew #
via Docker docker pull openapitools/openapi-generator-cli Basic Usage: # Generate Ruby SDK openapi-generator generate -i api.yaml -g ruby -o ./ruby-sdk # Generate Python SDK openapi-generator generate -i api.yaml -g python -o ./python-sdk 19 -
OpenAPI Generator creates from this: Ruby method: client.reply_message(reply_message_request: request) Request
class: ReplyMessageRequest.new(reply_token:, messages:) Validation: Ensures replyToken is string, messages is array 20 -
This creates polymorphic message system: Single Message interface for all
message types Automatic type detection based on type property Type-safe casting to specific message classes Runtime validation ensures correct message structure 21 -
This YAML definition automatically generates: Type-safe Ruby classes with proper
validation IDE autocompletion for all properties Compile-time error checking for invalid values Consistent behavior across all language SDKs Mind = Blown! From YAML to working code in seconds! 22 -
OpenAPI Generator: Real Benefits One command generates complete SDK Consistent
structure across all languages Built-in validation and error handling Documentation included automatically 23 -
v2 SDK: No More God Class Maintenance! line-bot-sdk-ruby/ └── lib/line/bot/v2/
# v2 Implementation (specialized) ├── messaging_api/ # Messaging operations │ ├── api │ │ ├── api_client.rb # Core messaging client - 3,000+ lines │ │ └── api_blob_client.rb # Binary content handling │ └── models/ # 100+ type-safe classes │ ├── text_message.rb │ ├── flex_message.rb │ └── template_message.rb └── channel_access_token/ # OAuth management 100+ Auto-generated Models from OpenAPI Domain Separation with clear boundaries 25 -
5. v1 vs v2: The Strongest Difference JSON vs Class
Components - The fundamental transformation in API client architecture 26 -
v1: JSON/Hash-Based Architecture { type: "flex", altText: "this is a
flex message", contents: { type: "bubble", header: { type: "box", layout: "vertical", contents: [{ type: "text", text: "Header text" }] }, body: { type: "box", layout: "vertical", contents: [{ type: "text", text: "Body text" }] } } } 27 -
v2: Class-Based Architecture Line::Bot::V2::MessagingApi::FlexMessage.new( alt_text: 'this is a flex message',
contents: Line::Bot::V2::MessagingApi::FlexBubble.new( header: Line::Bot::V2::MessagingApi::FlexBox.new( layout: 'vertical', contents: [Line::Bot::V2::MessagingApi::FlexText.new(text: 'Header text')] ), body: Line::Bot::V2::MessagingApi::FlexBox.new( layout: 'vertical', contents: [Line::Bot::V2::MessagingApi::FlexText.new(text: 'Body text')] ) ) ) 28 -
Code Examples 1/6 - Type Safety & Error Detection -
# v1: Runtime errors only - message = { - type: "text", - txt: "Hello" # Typo, runtime crash - } - client.reply_message(token, message) + # v2: Compile-time checking + message = Line::Bot::V2::MessagingApi::TextMessage.new( + txt: "Hello" # IDE catches it + ) 29 -
Code Examples 2/6 - IDE Support & Developer Experience -
# v1: No autocompletion - { - type: "flex", - contents: { - type: "bubble" # What's available? - } - } + # v2: Full IntelliSense + FlexBubble.new( + # IDE shows all options + ) 30 -
Code Examples 3/6 - Error Messages - # v1: Vague
errors - begin - client.reply_message(token, invalid_message) - rescue => e - puts e.message # "400 Bad Request" - end + # v2: Clear validation + begin + TextMessage.new(text: nil) + rescue ArgumentError => e + puts e.message # "text cannot be nil" + end 31 -
Code Examples 4/6 - Client Architecture Transformation - # v1:
God Class handles everything - client = Line::Bot::Client.new { |config| - config.channel_token = ENV['LINE_CHANNEL_ACCESS_TOKEN'] - } - # 50+ methods! - client.push_message(user_id, message) - client.get_profile(user_id) - client.create_rich_menu(menu) - client.validate_signature(body, signature) + # v2: Specialized clients + messaging_client = MessagingApi::ApiClient.new( + channel_token: ENV['LINE_CHANNEL_ACCESS_TOKEN'] + ) + liff_client = Liff::ApiClient.new( + channel_token: ENV['LINE_CHANNEL_ACCESS_TOKEN'] + ) + # Focused: ~10 methods each 32 -
Code Examples 5/6 - Message Construction - # v1: Nested
hashes - template_message = { - type: 'template', - altText: 'Please select', - template: { - type: 'buttons', text: 'Choose action', # Complex nesting - actions: [{ label: 'Action 1', type: 'postback', data: 'action1' }] - } - } + # v2: Type-safe classes + template_message = TemplateMessage.new( + alt_text: 'Please select', + template: ButtonsTemplate.new( + text: 'Choose action', # Clear structure + actions: [PostbackAction.new(label: 'Action 1', data: 'action1')] + ) + ) 33 -
Code Examples 6/6 - FlexMessage: The Key Transformation - #
v1: Nested hashes - { - type: "flex", - altText: "Flex message", - contents: { - type: "bubble", # Deep nesting maze - header: {type: "box", layout: "vertical", contents: [{ type: "text", text: "Header" }]}, - body: {type: "box", layout: "vertical", contents: [{ type: "text", text: "Body" }]} - } - } + # v2: Structured classes + FlexMessage.new( + alt_text: "Flex message", + contents: FlexBubble.new( # Clean hierarchy + header: FlexBox.new(layout: "vertical", contents: [FlexText.new(text: "Header")]), + body: FlexBox.new(layout: "vertical", contents: [FlexText.new(text: "Body")]) + ) + ) 34 -
The Ultimate Showdown: v1 vs v2 1/2 Round v1 (Hash)
v2 (Class) Winner Type Safety Runtime crash IDE catches v2 IDE Support No hints Full completion v2 Bugs After deploy During dev v2 Docs Check wiki Code = docs v2 Refactor Scary Confident v2 Speed Manual Generated v2 35 -
The Ultimate Showdown: v1 vs v2 2/2 Round v1 (Hash)
v2 (Class) Winner Simple Just hash Learning curve v1 Onboard Quick start More concepts v1 Final Score: v2 Wins 6-2! 36 -
6. Results Achieved Measurable impact on development speed, code quality,
and team productivity 37 -
Transformation Results Delivery Speed: Months → Days Quality: Fewer bugs,
zero errors Scale: More languages, less work Maintenance Cost: High → Minimal Developer Experience: Frustration → Joy Real transformation! So how can YOU achieve similar results? Let's distill the key insights... 38 -
7. Key Takeaways Your OpenAPI adventure starts now - actionable
insights and practical next steps 39 -
For API Providers 1. Start with OpenAPI-first design - Specification
drives everything 2. Embrace automation - Let machines do repetitive work For the Industry 1. Cross-language consistency - Same experience everywhere 2. Focus on value-add work - Not routine maintenance 40 -
Your OpenAPI Adventure Starts Now! "Don't just build APIs. Build
ecosystems that scale." Begin Your Journey: Audit: How many manual SDK updates are waiting? Start Small: Convert one endpoint to OpenAPI specification Automate: Generate your first SDK with openapi-generator Scale: Deploy CI/CD automation for all endpoints Expand: Add new language SDKs with zero additional effort 41 -
Thank You! How OpenAPI Is Transforming API Client Development COSCUP
2025: Thank you! 謝謝! Direct Links: Twitter/X: @_4geru LINE OpenAPI: github.com/line/line-openapi 42