Ruby

The genko.me delivery API is a REST API: send a GET request with an X-API-KEY header and receive JSON. Ruby's standard net/http and json libraries are enough.

What to use

There is no official Ruby gem. You do not need another Gemfile dependency. net/http, json, and uri handle requests, and openssl handles signature verification; all are part of the standard library.

If your project already uses Faraday or httprb, you can use it instead. The delivery API requires one header and query parameters, so it works with any HTTP client. This guide uses net/http to avoid adding a dependency.

Good fit

• Add announcements, case studies, or job posts managed by non-engineers to a Rails app.
• Fetch entries during a Jekyll, Bridgetown, or Middleman build.
• Move frequently updated pages of a small Sinatra site into a CMS.
• Fetch lists of entries in a rake task or scheduled job and pass them to another system.

Limitations

• Creating or updating entries. The delivery API is read-only. Create and publish entries in the dashboard.
• Using it like ActiveRecord. The API only supports HTTP GET. There is no lazy loading of associations or chainable where; set the reference expansion level with depth.
• Showing a list of drafts. A draftKey can fetch only one entry.
• Full-text search. q performs a case-insensitive substring match, without relevance ranking or linguistic analysis.

Cache the response

Calling net/http in every Rails controller request adds an external HTTP round trip to every page view. The limit is 300 requests per minute per API key. Cache results with Rails.cache.fetch or similar, then invalidate them with a webhook.

Delivery API responses include Cache-Control: private, no-store, so an intermediate HTTP cache will not cache them. Manage the cache in your app.

Next steps

• Get started: configure an API key and show a list and a single entry
• Tutorial: pagination, previewing drafts, and webhook signature verification
• Delivery API: endpoint and response specifications