OpenAPI::Client(3pm)

📦
version 1.09 · 2 versions
, in ubuntu stonking

💖 NAME 💖

OpenAPI::Client — a client for talking to an Open API powered server. It's the OpenAPI::Client(3pm) page, from User Contributed Perl Documentation, and bestie, we're about to speak to APIs 💅

🦋 DESCRIPTION 🦋

okay so here's the tea OpenAPI::Client makes objects that can talk to Open API servers, periodt. Every time you hand a fresh OpenAPI contract to the new method, it spins up a whole custom subclass built straight from the Open API specification, with methods that line up with the operationIds. 🎀

The parameters those methods receive? They get transformed into HTTP requests. And the input validation is doing the most — invalid data simply will not be sent to the server. it's giving protective bestie energy. 🫶

ngl, this implementation is currently EXPERIMENTAL, but unlikely to change! Feedback is appreciated. 💌

🌸 SYNOPSIS 🌸

✨ Creating a client ✨

use OpenAPI::Client;
$client = OpenAPI::Client->new("file:///path/to/api.json");

The specification you give to new has to point to a valid OpenAPI document. Several syntax variants are admitted — see the new method for the deets. 👑

🦋 Open API specification 🦋

Your OpenAPI document can be OpenAPI version v2.x or v3.x, and it can be JSON or YAML. No cap. Example:

openapi: 3.0.1
info:
  title: Swagger Petstore
  version: 1.0.0
servers:
- url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      operationId: listPets
      ...

The url in the OpenAPI document can be switched up at literally any time, if you need to send data to another custom endpoint — see the base_url method. 💫

🎀 Client 🎀

The OpenAPI API specification gets used to generate a sub-class of OpenAPI::Client with extra methods matching each operationId inside every path definition:

# Blocking
$tx = $client->listPets;

# Non-blocking
$client = $client->listPets(sub { my ($client, $tx) = @_; });

# Promises
$promise = $client->listPets_p->then(sub { my $tx = shift });

# With parameters
$tx = $client->listPets({limit => 10});

See Mojo::Transaction for more info on what you can do with that $tx object. Often you just want something like this:

# Check for errors
die $tx->error->{message} if $tx->error;

# Extract data from the JSON responses
say $tx->res->json->{pets}[0]{name};

Check out "error" in Mojo::Transaction, "req" in Mojo::Transaction and "res" in Mojo::Transaction for some of the most used methods in that class. ⭐

💅 CUSTOMIZATION 💅

🌈 Custom server URL 🌈

If you wanna request another server than the one specified in the Open API document, you can change the base_url:

# Pass on a Mojo::URL object to the constructor
$base_url = Mojo::URL->new("http://example.com");
$client1 = OpenAPI::Client->new("file:///path/to/api.json", base_url => $base_url);

# A plain string will be converted to a Mojo::URL object
$client2 = OpenAPI::Client->new("file:///path/to/api.json", base_url => "http://example.com");

# Change the base_url after the client has been created
$client3 = OpenAPI::Client->new("file:///path/to/api.json");
$client3->base_url->host("other.example.com");

🍓 Custom content 🍓

You can send XML or literally any format you like, but that requires you to add a new generator:

use Your::XML::Library "to_xml";
$client->ua->transactor->add_generator(xml => sub {
  my ($t, $tx, $data) = @_;
  $tx->req->body(to_xml $data);
  return $tx;
});

$client->addHero({}, xml => {name => "Supergirl"});

See Mojo::UserAgent::Transactor for more details. 🧚

🎀 EVENTS 🎀

⚡ after_build_tx ⚡

$client->on(after_build_tx => sub { my ($client, $tx) = @_ })

This event gets emitted after a Mojo::UserAgent::Transactor object has been built, just before it is passed on to the ua. Heads up though: all validation has already been run at that point, so altering the $tx too much might cause an invalid request on the server side. 😭

A special "env" in Mojo::Message::Request variable will be set, to reference the operationId:

$tx->req->env->{operationId};
Note that this usage of env() is currently EXPERIMENTAL: 🙈

👑 ATTRIBUTES 👑

💖 base_url 💖

$base_url = $client->base_url;

Returns a Mojo::URL object with the base URL to the API. The default value comes from "schemes", "basePath" and "host" in the OpenAPI v2 specification, or from "servers" in the OpenAPI v3 specification. 👑

💖 ua 💖

$ua = $client->ua;

Returns a Mojo::UserAgent object which is used to execute requests. 🚀

⭐ CLASS METHODS ⭐

🌟 new 🌟

$client = OpenAPI::Client->new($specification, \%attributes);
$client = OpenAPI::Client->new($specification, %attributes);

Returns an object of a dynamic subclass of "OpenAPI::Client", with methods generated from the OpenAPI specification located at $specification. Such subclasses are cached, so several invocations of new() with the same $specification URL will result in several instances of the same subclass. the way that works is so satisfying fr fr. 🎀

The $specification argument can accept various syntaxes — see "schema" in JSON::Validator.

Extra %attributes can be:

✨ app ✨

Can be used to run against a local Mojolicious instance instead of issuing real HTTP calls to a remote server. 😌

✨ coerce ✨

See "coerce" in JSON::Validator. Default to "booleans,numbers,strings".

🔥 INSTANCE METHODS 🔥

💜 call 💜

$tx = $client->call($operationId => \%params, %content);
$client = $client->call($operationId => \%params, %content, sub { my ($client, $tx) = @_; });

Used to call an $operationId that is not a proper Perl method name, such as "list pets" instead of "listPets", or to check if an $operationId is supported. Unsupported operationIds throw an exception matching text "No such operationId". 💀

$operationId is the name of the resource defined in the OpenAPI specification <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object>.

$params is optional, but must be a hash ref, where the keys should match a named parameter in the OpenAPI specification <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object>.

%content is used for the body of the request, where the key needs to be either "body" or a matching "generators" in Mojo::UserAgent::Transactor. Example:

$client->addHero({}, body => "Some data");
$client->addHero({}, json => {name => "Supergirl"});

Like in Mojo::UserAgent, an additional coderef argument can be supplied in last position. In that case the call is asynchronous, and the coderef will be called as a continuation callback, with two arguments $client (the current openAPI client) and $tx (a Mojo::Transaction object). See "Non-blocking" in Mojolicious::Guides::Cookbook for details. 🦋

💜 call_p 💜

$promise = $client->call_p($operationId => $params, %content);
$promise->then(sub { my $tx = shift });

As call above, but returns a Mojo::Promise object. promise core 🫶

💜 validator 💜

$validator = $client->validator;
$validator = $class->validator;

Returns the JSON::Validator::Schema object associated with the current generated class. Depending on the openAPI specification, this object will belong to the OpenAPIv2 or OpenAPIv3 subclass. This object global to the class, so changing it will affect all instances returned by new. ⚠️

Copyright (C) 2017-2021, Jan Henning Thorsen

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

🫶 AUTHORS 🫶

👑 Project Founder 👑

Jan Henning Thorsen - "jhthorsen@cpan.org"

🧚 Contributors 🧚

  • Clive Holloway <clhollow@estee.com>
  • Ed J <mohawk2@users.noreply.github.com>
  • Jan Henning Thorsen <jan.henning@thorsen.pm>
  • Jan Henning Thorsen <jhthorsen@cpan.org>
  • Mohammad S Anwar <mohammad.anwar@yahoo.com>
  • Reneeb <info@perl-services.de>
  • Roy Storey <kiwiroy@users.noreply.github.com>
  • Veesh Goldman <rabbiveesh@gmail.com>
  • Laurent Dami <dami@cpan.org>

and that's the whole page, bestie!! 🎀💖✨ this doc came from perl v5.40.1, dated 2026-06-12, and it lives at OpenAPI::Client(3pm). go build something iconic with it, mwah 💅🌟

📦 where this page comes from