Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Perl Petstore Enhanced REST API Framework


This is a much enhanced, yet still minimal, version of the Swagger Petstore sample code using Perl Mojolicious/Swagger2.

Using this sample code and installation guide as a framework, an experienced programmer can write a feature-rich REST API server in about an hour.


Anybody can hand-roll a REST API server, but the tricky part is generating and maintaining 100% accurate validation and documentation for end-users.

Perl Swagger2 lets you define your API spec in YAML or JSON, then automatically generates the following:

  • input and output parameter validation
  • controller (aka dispatcher or router) to map URLs to function calls
  • displays API documentation in HTML for end-users
  • automatic content negotiation for JSON, XML and text.
  • displays routes for debugging:

  +/               GET  "infoPets"

  +/doc            GET  "docPets"

  +/pets           GET  "listPets"

  +/pets           PUT  "createPets"

  +/pets        DELETE  "deletePets"

  +/admin/ping     GET  "pingPets"

  +/admin/menu     GET  "menuPets"

  +/pets/(:petId)  GET  "showPetById"

API Consumer Features

  • GET /api/v1.0 shows HTML route summary (instead of only being available on error pages)
  • GET /api/v1.0/doc shows API spec in HTML format
  • paging with offset and limit in /pets
  • content negotiation with ?format=json and ?format=xml to automatically select output format for non-documentation routes
  • HTTP method override for client programs to use POST with X-HTTP-Method-Override: {PATCH, PUT, DELETE} where necessary
  • Param and Basic Authentication for both API and browser clients. Default is username=Perl, password=Bender.
  • non-trivial sample code for several programming languages (bash, Go, Java, Perl, PHP, Python, Ruby) in samples/ with authentication, error handling and timeout.

Developer Features

  • sets common options like mode=production, secrets and title
  • /admin route with separate admin username and password
  • has complete set of typical development directories, including public/, samples/, t/, and templates/
  • shows how to correctly version the API in the format v1.0
  • stores sample pet data in an array to avoid database dependencies
  • command line examples of various Mojo and Swagger2 test and validation features in
  • up-to-date Swagger2 api.spec properties in JSON and YAML formats
  • shows how to override automatic rendering by the Swagger2 controller using render()
  • good test coverage.

Operations Features

  • built-in process health-check monitoring endpoint: /admin/ping => pong
  • my_throttle skeleton function
  • mod_perl compatible - just add your functions to
  • minimal dependencies - likely works with your existing version of Perl
  • adequate authentication for Intranet use already built-in.

Getting Started

git clone


cpan Mojolicious Mojolicious::Plugin::MethodOverride Swagger2 XML::Simple Test::Mojo JSON

chown -R root:root perl-petstore-enhanced/pets

cd perl-petstore-enhanced/pets

vi api.spec # configure 'host', 'basePath' and 'contact' properties near top of file

vi cgi-bin/pets.cgi # configure the install path, username, password, domain, schema  and base_url



Getting Finished

  • now you can finish writing your own API with customized module and endpoint names
  • change "Pets" to your module name, then "Pet" to your module name
  • run the prove test command
  • download Postman to easier do REST API development

Convert Spec

Privacy and Security

The point of an API server is to, well, serve.

But you can take the following security precautions before deploying on a web server:

  • it's mandatory to use SSL in production or over the Internet because of payload injection or credentials sniffing
  • non-SSL connections should be rejected outright, not redirected
  • move the Controller module to some place outside DocumentRoot, like /perllib
  • put configuration settings and passwords some place outside DocumentRoot, like /perllib
  • remove the development templates, which display your environment settings.
  • the Petstore files and directories should be owned by root and not writable by anybody else
  • if you use a database, ensure your queries that allow user input use placeholders like ?.

Some more general web server security tips:

  • httpd should run as a non-privileged user like httpd, UID=510, GID=510
  • if it is a restricted access server, use an iptables rule or TCP wrappers to only allow VPN access


  • cleanup /doc and 404 page content
  • role auth?


Some things to think about:

cass_top screenshot cass_top screenshot


Perl and Mojolicious enhanced sample REST API Server Framework





No releases published


No packages published