RestClient.jl

As simple as a RESTful API may be, there's often a fair bit of boilerplate involved in making well-formed requests, handling serialisation and deserialisation, request limiting, and result pagination.

RestClient aims to take care of as much of this boilerplate as possible without compromising on flexibility. See the tutorial for a sense of what this looks like in practice.

Getting started

Set the API configuration

@globalconfig RequestConfig("https://api.example.com")

See @globalconfig and RequestConfig for more information.

Define response types

@jsondef struct Item
    id."item_id"::Int
    name::String
    description::String
end

@xmldef struct Item
    id."@id"::Int
    name."@name"::String
    description."text()"::String
end

See @jsondef and @xmldef for more information.

Define request payloads

For endpoints that send a body, payload types can be defined just as concisely. @jsondef types double as JSON payloads, while form submissions have dedicated macros:

@formdef struct Login           # application/x-www-form-urlencoded
    username::String
    remember."remember-me"::Bool = false
end

@multipartdef struct Upload     # multipart/form-data
    file::Vector{UInt8}         # sent as an octet-stream part
    metadata::Item              # an @jsondef field → JSON part
end

See @formdef and @multipartdef for more information.

Declare endpoints

@endpoint item(id::Int) -> "items/{id}" -> Item

See @endpoint for more information.

Stream incremental responses

For APIs that deliver a response piece by piece (token streams, event feeds), name a Stream output type and iterate the elements as they arrive:

@endpoint chat(; messages) -> "messages" -> Stream{Delta}

See the streaming manual for more information.

Extra functionality

• Pagination
• Response post-processing
• Caching
• Custom data formats
• Form and multipart payloads (via @formdef and @multipartdef)
• Streaming responses (via SSE and NDJSON)
• Authentication (Bearer, Basic, header, and query schemes)
• Rate limiting (by reading the relevant HTTP response headers)

Request data flow

As detailed in the Request docstring, this is the flow of calls when making a request:

         ╭─╴config╶────────────────────────────╮
         │     ╎                               │
         │     ╎        ╭─▶ responsetype ╾─────┼────────────────┬──▶ dataformat ╾───╮
Request╶─┤     ╰╶╶╶╶╶╶╶╶│                      │                ╰─────────╮         │
         │              ├─▶ urlpath ╾────╮     │      ┌┄┄┄┄debug┄┄┄┐      │  ╭──────╯
         │              │                ├──▶ url ╾─┬─━─▶ request ╾━┬─▶ interpret ╾──▶ data
         ├─╴endpoint╶───┼─▶ parameters ╾─╯          │               │                   │
         │              │                           │               │             ╭─────╯
         │              ├─▶ parameters ╾────────────┤               ╰─────────╮   │
         │              │                           │                      postprocess ╾──▶ result
         │             *╰─▶ payload ─▶ writepayload╶╯                           │
         │                    ╰─▶ dataformat ╾╯                                 │
         ╰─────────┬────────────────────────────────────────────────────────────╯
                   ╰────▶ validate (before initiating the request)

 * Only for POST requests   ╶╶ Optional first argument