Building SDKs
Every Rainkit tutorial used to start with the same ten lines: build the URL, add the header, set a timeout, check the status, parse the JSON. Developers copied them, got them slightly wrong, and asked about them on the forum. An SDK makes those ten lines disappear, but only if it is designed around the developer, not around the API.
The rule
A good SDK feels native to its language and hides the plumbing.
An SDK (software development kit) here means a library that wraps an API for one programming language. Compare calling Rainkit by hand in Python:
import os
import requests
resp = requests.get(
"https://api.rainkit.example/v1/forecast",
params={"lat": 18.52, "lon": 73.86, "hours": 6},
headers={"Authorization": f"Bearer {os.environ['RAINKIT_KEY']}"},
timeout=10,
)
resp.raise_for_status()
first_hour = resp.json()["hours"][0]with calling it through the SDK:
from rainkit import Rainkit
client = Rainkit() # reads RAINKIT_KEY from the environment
forecast = client.forecast(lat=18.52, lon=73.86, hours=6)
print(forecast.hours[0].rain_chance)The plumbing the SDK hides: the base URL, authentication, timeouts, retrying after a 429 or a 5xx with a sensible wait, turning error responses into clear exceptions such as RateLimitError, and turning JSON into typed objects that an editor can autocomplete.
Native means it follows each language's habits. Python uses snake_case names, keyword arguments and exceptions. JavaScript uses camelCase and promises you can await. Go returns an error value alongside the result. The same API should feel different in each language, because each language's developers expect different things.
SDKs are versioned with semantic versioning, MAJOR.MINOR.PATCH: a bug fix bumps PATCH, a new backwards-compatible feature bumps MINOR, and anything that breaks existing code bumps MAJOR. Many teams generate a first draft of each SDK from a machine-readable API description such as OpenAPI, then polish it by hand, because generated code alone rarely feels native.
Finally, an SDK needs a few docs of its own: a README with the install command and the main example at the top, and a changelog that lists what changed in every release, so developers can upgrade with confidence.
The shortcut
Write the dream code first. Before building anything, write the few lines a developer wishes they could write in that language. Then build the SDK to make exactly that code work.
Dream code
const rk = new Rainkit();thenconst f = await rk.forecast({ lat: 18.52, lon: 73.86, hours: 6 });
Drills
Answer fast — trust the rule.
Which of these is a job an SDK should do for the developer?
Rainkit's Python SDK is at 2.3.1. It adds a new alerts() method without changing anything that exists. What is the new version?
Which Python call feels most native?
What is the point of writing "dream code" before building an SDK?
At version 2.4.0, the team renames forecast() to get_forecast(). Which version must the release be?
Remember
- A good SDK feels native to its language and hides the plumbing.
- Shortcut: write the dream code first, then build the SDK to make it true.
- Trap: one SDK translated word for word into every language, or a breaking change without a new MAJOR version.