Writing an API client¶
examples/github_repo.kod reads a repository's details and its open issues from
the GitHub API. It is about a hundred lines and uses every piece of the
standard library that a client needs; this page walks through it.
anthropics/anthropic-sdk-python
(no description)
language: Python
stars: 4030, forks: 901
license: Apache-2.0
open issues:
#2050 fix(streaming): keep compaction metadata when a delta omits encrypted_content
#2049 fix(decoders): close the response when JSONL decoding fails
#2048 fix(tools): don't coerce a non-object tool input in the session runner
Set GITHUB_TOKEN to send a bearer token (private repositories need one), and
GITHUB_API to talk to something other than https://api.github.com. The tests
use that to run the example against a local stand-in server
(tests/support/github_api.kod), so they need no network.
The pieces¶
Arguments and environment. main(argv: [str]) receives the command line,
with the program's name first. env.get("GITHUB_TOKEN") returns a str?, and
x? or default handles a missing variable (Built-ins).
The client. What every request to the service needs goes on a Client once: its
headers, its deadline. The example wraps it in a small GitHub type, so main reads
as github.repo(name) and github.open_issues(name, limit: 3). One Client serves
both requests, which keeps the connection from the first and uses it for the second
(HTTP client).
let client = Client(deadline: Duration(seconds: 15))
client.headers.add("Accept", "application/vnd.github+json")
client.headers.add("Authorization", "Bearer " + token)
let response = try client.get(url)
A single request can override any of that with Options, for instance
client.get(url, options: Options(deadline: Duration(seconds: 2))). Client.get follows
redirects, enforces the size limits and the deadline, and picks TCP or TLS from the
URL.
Query strings. Build them with Query, which encodes names and values, rather
than by joining strings:
let query = Query()
query.add("state", "open")
query.add("per_page", "3")
let url = with_query("/repos/" + name + "/issues", query)
Reading JSON. json.parse returns Value or Error. The accessors never fail,
so a missing or null field is a fallback, not a crash:
func text_of(anon v: json.Value, key: str, fallback: str) -> str {
return v.get(key).as_str()? or fallback
}
license.get("spdx_id") on a null license is Null, and as_str of
that is none, which ? or "none" turns into the text none.
Errors. A non-2xx response is not a Kod error; fetch hands it back so you can
read what the API said. The example turns it into its own ApiError and
throws it, so that callers see one failure path for "the request failed" and
"the API refused":
Network failures arrive as an IoError with a kind (ConnectionRefused,
TimedOut, HostNotFound, Tls, Protocol, ...); see Streams.
main here turns every failure into error: ... on standard error and an
exit status of 1, and a bad command line into 2.
Sending JSON¶
Writing to an API is the same, with a body. ObjectBuilder keeps the keys and
values in step, and post sets the length and the content type:
import "json"
import "net/http" { post }
let body = json.ObjectBuilder()
body.put_str("title", "It crashes")
body.put_str("body", "Steps to reproduce: ...")
body.put("labels", json.array_of([json.str_value("bug")]))
let payload = kod_str_to_bytes(body.build().emit())
let response = try post(
"https://api.example.com/issues",
payload,
content_type: "application/json",
)
What to know before relying on it¶
get,postandfetchopen a connection for each request and close it. A program that makes many requests to one host should create aClientand call itsget,postandfetchinstead, which keep connections for reuse (Connection reuse).timeoutapplies to the connect, the TLS handshake and each read or write. Setdeadlineto bound a request as a whole (Deadlines).- TLS goes through the system's SecureTransport, which speaks TLS 1.2 at most. A
server that insists on TLS 1.3 fails with a
Tlserror. - Numbers with a fraction or an exponent come back as
Decimaltext:as_int()isnonefor them,as_number_text()gives the digits, and.parse_float()on those turns them into afloat64.