How nisyuu/kendama works
Main Components
• Client Application: Represents the consumer’s application that includes and calls the kendama gem. This is where a developer would “require 'kendama'” and then invoke methods from the API (e.g., Kendama::V1Api#get_announcement_by_diff).
• API Client Module (Kendama::V1Api): This module, found in lib/kendama/api, acts as the primary interface for making API calls. It encapsulates HTTP calls to external endpoints.
• Models: Classes such as Kendama::Announcement and Kendama::ResponseBody (located in lib/kendama/models) represent the data structures that map to the API responses.
• Configuration & Error Handling: The configuration settings (in lib/kendama/configuration.rb) and error classes (Kendama::ApiError) provide management for setting API endpoints, credentials (if needed), and handling exceptions.
• OpenAPI Definitions: The openapi directory contains YAML definitions that describe the API contracts. This indicates that the gem was generated based on a well-defined API specification.
• Supporting Components: Test suites in the spec directory, documentation in the docs folder, CI/CD workflows (.github, .gitlab-ci.yml, .travis.yml), and the gemspec file for package information.
Relationships and Interactions
• A client application uses the Kendama gem to send requests. The client instantiates methods from Kendama::V1Api.
• The Kendama::V1Api module interacts with the models to format requests and parse responses.
• Kendama::Configuration supplies necessary settings and parameters to the API client.
• When an API call is made, the API client sends an HTTP request to the external 国税庁 API (e.g., using endpoints such as /1/diff, /1/num, or /1/valid).
• Responses from the external API are mapped to respective Ruby models.
• Error handling through Kendama::ApiError captures and propagates errors back to the client.
Architectural Patterns and Technologies
• The project uses the client library pattern where the gem abstracts the HTTP communication details.
• It follows a modular design separating API interface, data models, and configuration.
• Automated testing and CI/CD are integrated through the spec tests and various CI configurations.
• OpenAPI generated code indicates that any updates to the API can be regenerated while preserving consistent contract definitions.