Author image Nils Diewald
and 1 contributors


Mojolicious::Plugin::Util::Endpoint - Use Template URIs in Mojolicious


  # Mojolicious::Lite
  plugin 'Util::Endpoint';

  # Mojolicious

  my $rs = $mojo->routes;

  # Set endpoint
  my $r = $rs->route('/:user')->endpoint(
    webfinger => {
      query  => [
        q => '{uri}'

  return $self->endpoint('webfinger');
  # https://sojolicious.example/{user}?q={uri}

  $self->stash(user => 'Akron');

  return $self->endpoint('webfinger');
  # https://sojolicious.example/Akron?q={uri}

  return $self->endpoint(webfinger => {
    uri => 'acct:akron@sojolicious.example'
  # https://sojolicious.example/Akron?q=acct%3Aakron%40sojolicious.example


Mojolicious::Plugin::Util::Endpoint is a plugin that allows for the simple establishment of endpoint URIs. This is similar to url_for, but includes support for template URIs with parameters following RFC6570 Level 1 (as used in, e.g., Host-Meta or OpenSearch).



  # Mojolicious

  # Mojolicious::Lite
  plugin 'Util::Endpoint';

Called when registering the plugin.



  my $rs = $mojo->routes
  my $r = $rs->route('/suggest')->endpoint(
    opensearch => {
      scheme => 'https',
      host   => 'sojolicious.example',
      port   => 3000,
      query  => [
        q     => '{searchTerms}',
        start => '{startIndex?}'

Establishes an endpoint defined for a service. It accepts optional parameters scheme, host, a port and query parameters (query), overwriting the current values of url_for. Template parameters need curly brackets, optional template parameters need a question mark before the closing bracket. Optional path placeholders are currenty not supported. Returns the route.

Warning: Support for named routes to use with url_for was dropped in v0.19.



  # In Controller:
  #   Set endpoints:
  $self->endpoint(hub => 'http://sojolicious.example/search?q={searchTerm}');
  $self->endpoint(hub => Mojo::URL->new(''));

  #   Get endpoints:
  return $self->endpoint('webfinger');
  return $self->endpoint(webfinger => { user => 'me' } );

  # Interpolate arbitrary template URIs
  return $self->endpoint(
    'http://sojolicious.example/.well-known/webfinger?resource={uri}&rel={rel?}' => {
      'uri' => 'acct:akron@sojolicious.example',
      '?'   => undef

  # In Template:
  <%= endpoint 'webfinger' %>

Get or set endpoints defined for a specific service.

For setting it accepts the name of the endpoint and either a string with the endpoint URI or a Mojo::URL object.

For getting it accepts the name of the endpoint or an arbitrary template URI and additional stash values for the route as a hash reference. These stash values override existing stash values from the controller and fill the template variables.

  # In Controller:
  return $self->endpoint('opensearch');
  # https://sojolicious.example/suggest?q={searchTerms}&start={startIndex?}

  return $self->endpoint(opensearch => {
    searchTerms => 'simpson',
    '?' => undef
  # https://sojolicious.example/suggest?q=simpson

The special parameter ? can be set to undef to ignore all undefined optional template parameters.

If the defined endpoint can't be found, the value for url_for is returned.


  # In Controller:
  my $hash = $self->get_endpoints;

  while (my ($key, $value) = each %$hash) {
    print $key, ' => ', $value, "\n";

Returns a hash of all endpoints, interpolated with the current controller stash.

Note: This helper is EXPERIMENTAL and may be deprecated in further releases.



  $ perl endpoints

Show all endpoints of the app established by this plugin.


Mojolicious (best with SSL support).


Viacheslav Tykhanovskyi



Copyright (C) 2011-2021, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the same terms as Perl.