JSON API Client
Build a Ruby command-line client for a public JSON API, for example the GitHub API, to list a user's repositories or an organization's issues. Real APIs split results into pages, limit how many requests you can make, and sometimes fail, so the client follows pagination links, retries temporary errors with increasing waits, respects rate limits, and caches responses in Redis, so repeating a request is instant and doesn't use up your limit. The code is packaged as a gem, with the API logic separate from the command-line part. You'll learn HTTP with Net::HTTP, pagination through Link headers, caching and cache expiry with Redis, retries and timeouts, packaging with RubyGems, and testing HTTP code without calling the real API.
- Estimate
- ~11h
- Steps
- 6
- Completed by
- 0
- Proposed by
- codeseed.app
RubyGems · Redis
Project roadmap
- 01
Define what the client does
~1.5hCreate a gem skeleton with bundle gem. Write README.md listing the commands (for example repos USER and issues OWNER/REPO --state open), the output formats (a table or JSON), the options (--no-cache, --max-pages, an optional token from an environment variable) and how errors are shown. Done when: README.md shows example commands and their output.
- 02
Make requests and follow pages
~2hWrite an ApiClient class using Net::HTTP with open and read timeouts. Parse the JSON, and follow the next link from the Link header until there are no more pages or --max-pages is reached. Turn 404, 401 and other errors into your own exception classes with clear messages. Done when: listing the repositories of a user with more than 100 of them fetches every page.
- 03
Cache responses in Redis
~2hCache each response in Redis with the redis gem, keyed by the full URL, with an expiry time (for example 10 minutes). Store the ETag too, and send If-None-Match when a cached entry has expired: a 304 response means the cache is still valid, and doesn't count against GitHub's rate limit. If Redis isn't running, work without the cache and show a warning. Done when: a second identical command is served from the cache, and the tool still works with Redis stopped.
- 04
Handle retries and rate limits
~2hRetry timeouts and 5xx responses up to 3 times with exponential backoff. Read the rate limit headers: when the limit is used up, show when it resets instead of hammering the API, and honor Retry-After. Never retry 4xx errors other than 429. Done when: simulated failures are retried, and a used-up limit produces a clear message with the reset time.
- 05
Build the command line
~1.5hAdd an executable in exe/ using OptionParser that calls the client and prints results as an aligned table or JSON with --json. Exit with code 0 on success and non-zero on errors, with the message on stderr. Done when: the commands in README.md work after installing the gem locally with rake install.
- 06
Test without the real API
~2hWrite RSpec tests using WebMock to fake HTTP responses: following pages, stopping at --max-pages, 404 and 401 errors, retries after 503, rate limit handling, and caching with ETag and 304. Use a fake or test Redis for the cache tests. Done when: bundle exec rspec passes with the network disabled.
Resources
Ready to build this?
Get a GitHub repo and start building. Your AI reviewer checks each step as you go.
Tech stack