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

Transcript

1. 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
2. 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
3. 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
4. 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
5. 1. The Universal API Client Struggle Why API client development is universally challenging across languages and platforms 5
6. 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
7. 2. The Dark Ages of v1 When "God Class" ruled the kingdom and manual maintenance hit its limits 7
8. 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
9. 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
10. 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
11. 3. The Light: OpenAPI Changes Everything How OpenAPI became the game changer that revolutionized API client development 11
12. 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
13. 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
14. 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
15. 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
16. 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
17. 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
18. 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
19. 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
20. 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
21. 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
22. 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
23. OpenAPI Generator: Real Benefits One command generates complete SDK Consistent structure across all languages Built-in validation and error handling Documentation included automatically 23
24. 4. Revolution in v2 OpenAPI-driven automation transforms everything with specialized architecture 24
25. 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
26. 5. v1 vs v2: The Strongest Difference JSON vs Class Components - The fundamental transformation in API client architecture 26
27. 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
28. 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
29. 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
30. 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
31. 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
32. 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
33. 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
34. 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
35. 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
36. 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
37. 6. Results Achieved Measurable impact on development speed, code quality, and team productivity 37
38. 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
39. 7. Key Takeaways Your OpenAPI adventure starts now - actionable insights and practical next steps 39
40. 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
41. 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
42. 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