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.

Declare endpoints

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

See @endpoint for more information.

Extra functionality

• Pagination
• Response post-processing
• Caching
• Custom data formats
• 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