I’ve been doing a lot of work with REST APIs and microservices, so I decided to write a complete REST API framework in Perl based on the Mojolicious and Swagger2 Petstore sample.
You can git clone the repo and add a new feature in about 5 minutes with automatic parameter validation and documentation:
git clone git@github.com:jamesbriggs/perl-petstore-enhanced.git
cd perl-petstore-enhanced/pets
less ../README.md
vi api.spec set.sh cgi-bin/pets.cgi ./lib/Pets/Controller/Pet.pm
# add an Alias for cgi-bin/pets.cgi to httpd or nginx
# point your browser at http://www.example.com/api/v1.0/pets/1
# Good job. Have a Modelo! :)
or you can spend an hour to rename the files for your project and tweak it to requirements.
This project serves as a convenient bridge for those who:
- can write simple CGI programs and want to write a best-practises Swagger (OpenAPI) REST API server without climbing a steep learning curve, or
- want to write a quick proof-of-concept API server to be re-implemented in other languages or frameworks later, as your Swagger spec file is 100% reusable
- are targeting a small VM. This will work in a 2 GB RAM VM just fine, or on an existing server running httpd or nginx.
I learned the importance of Swagger2 and auto-generated documentation and validation when I was programming with the old Rackspace v1 and v2 APIs.
People asked me, “How did you do that? You must have really wanted it!” since the Rackspace sample code, docs and live API didn’t match. My secret: I actually guessed URLs in the browser to find the endpoints I needed. Swagger prevents that problem from ever happening.
http://editor.swagger.io/#/