This is an alternative router/dispatcher to Swi-Prolog's http_dispatch module. The main motivation for creating this module was more convenient (less verbose) implementation of RESTful web services.

![Build Status](


:- use_module(library(http/thread_httpd)).
:- use_module(library(arouter)).

:- route_get(hello/Name, handle_hello(Name)).

    format('Content-Type: text/plain; charset=UTF-8~n~n'),
    format('Hello ~w', [Name]).

:- http_server(route, [port(8008)]).

Save it to a file, run it, and then visit http://localhost:8008/hello/world.

Path terms

Normal path terms correspond directly to URL paths with the implicit root (/) symbol. For example, path/to/something corresponds to URL ``. To match the root itself, / alone must be used. To match an URL path with a slash in the end, an empty atom has to be used at the end of the path term. For example, to match URL ``, a path term path/to/something/'' must be used.

Using with http_dispatch

Make fallback to http_dispatch/1 like this:

(   route(Request)
->  true
;   http_dispatch(Request)).

and use handle_request/1 as the handler in http_server.


Routes can have intermediate goals. The following example is cheking auth information before executing the handler:

:- route_get(api/resource, auth, handle_resource).

(   http_session_data(user(User)),
    memberchk(role(admin), User)
->  call(Next)
;   current_request(Request),
    memberchk(path(Path), Request),
    http_reply(forbidden(Path), Out, [])).


The before-handler predicate calls its first argument when the request should pass it. Otherwise it should produce the response itself.

Route-path matching

A path will match the route when:

Route priority

Routes are tested in reverse to the adding order. Overlapping routes can be added. Structurally equivalent routes cannot be added. Routes are overlapping when one route has atom in position of route variable in the other. Routes are structurally equivalent when:

Structural equivalence is used for detecting duplicate rules. This plays nice with the make/0 goal.

Non-deterministic routing

In some cases another matching (overlapping) route might have to be tried. This can be done by throwing arouter_next from the current route handler. Example:

:- route_get(something/specific, handle_specific).


:- route_get(something/Generic, handle_generic(Generic)).

    (   Generic = specific
    ->  throw(arouter_next)
    ;   ...).

The handler handle_specific will handle the request in this case after throwing arouter_next from the handle_generic handler (handlers are tried in reverse order of adding them).

List of predicates

Adding new routes

`route_get(+Route, :Goal)` registers a new GET handler.

`route_put(+Route, :Goal)` registers a new PUT handler.

`route_del(+Route, :Goal)` registers a new DELETE handler.

`route_post(+Route, :Goal)` registers a new POST handler.

`route_get(+Route, :Before, :Goal)` registers a new GET handler with a before action.

`route_put(+Route, :Before, :Goal)` registers a new PUT handler with a before action.

`route_del(+Route, :Before, :Goal)` registers a new DELETE handler with a before action.

`route_post(+Route, :Before, :Goal)` registers a new POST handler with a before action.

`new_route(+Method, +Route, :Goal)` registers a new custom method handler.

`new_route(+Method, +Route, :Before, :Goal)` registers a new custom method handler with a before action.

All predicates above will throw an error when the Route does not contain the suitable term.

Route handler predicates can take variables from the route. Example:

:- http_get(post/show/Slug, post_show(Slug)).


However, they do not take the Request argument, unlike the http_dispatch handlers. To obtain the current request, use the http_current_request/1 predicate.


route(+Request) - takes given request and attempts to find suitable handler.

Request must contain terms method(Method) and path(Path). Throws handler_failed(Method, Path) when handler was found but it failed during execution.

Inspecting routes

Use the `route(?Method, ?Route, ?Before, ?Goal)` predicate.

Removing routes

Use the route_remove(Method, Route) predicate. Both arguments can be unbound or partially instantiated.


To install as a package:


Tested with Swi-Prolog 7.x but should work with earlier versions too.

Full API documentation


Running tests

In the package root, insert into swipl:


Or if you cloned the repo:

make test


Enable debugging with:

?- use_module(library(debug)).
?- debug(arouter).


Bug reports/feature requests

Please send bug reports/feature request through the GitHub project page.


The MIT license. See the LICENSE file.

Prolog files

examples/example.plShow source
examples/fallback.plShow source
pack.plShow source
prolog/arouter.plShow source
new_route/3Registers a new method-specific route handler.Source
new_route/4Registers a new method-specific route handler.Source
path_to_route/2Turns path atom like '/path/to/something' into a Prolog term path/to/something.Source
route/1Routes the request into an handler.Source
route/4Retrieves currently registered routes.Source
route_del/2Registers a new DELETE route handler.Source
route_del/3Registers a new DELETE route handler.Source
route_get/2Registers a new GET route handler.Source
route_get/3Registers a new GET route handler.Source
route_post/2Registers a new POST route handler.Source
route_post/3Registers a new POST route handler.Source
route_put/2Registers a new PUT route handler.Source
route_put/3Registers a new PUT route handler.Source
route_remove/2Removes the given route.Source
tests/tests.plShow source