Generating a custom Ruby SDK for your web service or Rails API using Smithy

Have you ever wanted a Ruby client API to communicate with your web service? Smithy is a protocol-agnostic language for defining services and SDKs. Smithy Ruby is an implementation of Smithy that generates a Ruby SDK using a Smithy model. In this talk, we will explore Smithy and Smithy Ruby to learn how to generate custom feature-rich SDKs that can communicate with any web service, such as a Rails JSON API.

1. Generating a custom Ruby SDK for your web service or Rails API Matt Muller SDE @ AWS 1

2. Who am I? Example Use Case and Service Smithy Overview Using Smithy to model and generate an SDK Deep dive into SDK usage and components Final thoughts Agenda 2

3. Software Engineer @ AWS (AWS SDK for Ruby) Ruby advocate First time presenting (at a developer conference) First time in Japan 3 Who am I?

4. Let’s get started… 4

5. Use Case Scenario 5

6. Example Application 6 “High Score Service”

7. Create Rails API 7

8. Scaffolding 8

9. Migrate database 9

10. Run server 10

11. Call our API 11

12. Generating an SDK for your API in Smithy 12

13. What is Smithy? Smithy is a language for defining services and SDKs. 13

14. Features of Smithy 14 Protocol-agnostic Designed to evolve API governance Resource based Works for any programming languages Describe services running in any environment Works with any transport format Extended through traits Extensible meta-model Avoid breaking changes Customizable API standards Validation rules across all APIs Models are defined by resources and operations Rich information for model transformations

15. Installing smithy-cli 15

16. Modeling the High Score service 16

17. Writing the model 17 model/high-score- service.smithy

18. Writing the model (continued) 18 Map to CRUD controller actions!

19. Writing the model (continued) 19 high_scores_controller.rb in myapp

20. Writing the model (continued) 20

21. Writing the model (continued) 21 high_scores_controller.rb in myapp

22. Writing the model (continued) 22 seeds.rb in myapp

23. Writing smithy- build.json 23

24. Generating the SDK 24

25. What’s included? 25

26. Using the SDK 26

27. Using the SDK (continued) 27

28. Using the SDK (continued) 28

29. How does it work? 29

30. Benefits of a Smithy Ruby SDK Easy to use Rich features Highly extensible at runtime Code generated Bring your own protocol and integrations 30

31. Public Features 31

32. Client API entry point Accepts configuration Calls operations 32

33. Client (continued) 33

34. Config Configure options and components for your SDK Per-operation override of config 34

35. Config (continued) 35

36. Types Data containers for input and output 36

37. Types (continued) 37

38. Logging Standard Ruby Logger Debug SDK internals or wire logging 38

39. Logging (continued) 39

40. Errors Standard Ruby Exceptions Follows a hierarchy Modeled or unmodeled error handling 40

41. Errors (continued) 41

42. Errors (continued) 42 models/high-score- service.smithy models/ high_score.rb in myapp

43. Errors (continued) 43

44. Errors (continued) 44

45. HTTP Client Bring your own HTTP Client Includes a Net::HTTP default 45

46. HTTP Client (continued) 46

47. Retries Retry network errors Retryable modeled errors Custom retry strategy 47

48. Retries (continued) 48

49. Retries (continued) 49

50. Retries (continued) 50

51. Stubbing Mock responses for testing Does not use the network 51

52. Stubbing (continued) 52

53. Interceptors Lifecycle hooks into the SDK Modify input, output, request, or response 53

54. Interceptors (continued) 54

55. Interceptors (continued) 55

56. Plugins Distributable code that modifies config 56

57. Plugins (continued) 57

58. Waiters ”waits” (blocks) until some condition Uses polling on an interval basis 58

59. Waiters (continued) 59

60. Waiters (continued) 60

61. Paginators Paginated service calls Enumerators for both pages and items 61

62. Paginators (continued) 62

63. Paginators (continued) 63

64. Other features Modeled auth (Bearer, SigV4, HTTP basic/digest) Modeled and dynamic endpoint resolution DNS resolving hooks in the HTTP client Connection pooling Your next great idea  64

65. Diving deeper into internals … 65

66. Builders 66

67. Parsers 67

68. Validators 68

69. Params 69

70. Stubs 70

71. Middleware 71

72. Middleware (continued) 72

73. What do you think? Experimental Feedback welcomed! Backbone of a future version of AWS SDK for Ruby 73

74. Matt Muller GitHub: mullermp No other socials 74 Smithy Ruby https://github.com/smithy-lang/smithy-ruby Today’s Demo https://github.com/mullermp/rubykaigi2024