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 API endpoint in about 5 minutes with automatic parameter validation and documentation:
git clone firstname.lastname@example.org:jamesbriggs/perl-petstore-enhanced.git
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.
Also of note is the samples/ folder, which has non-trivial client programs in several languages (bash, Java, Perl, PHP and Ruby.)
I learned the importance of Swagger2 and auto-generated API documentation and validation when I was programming with the old Rackspace Cloud v1 and v2 APIs.
People asked me, “How did you get anything to work? You must have really wanted it!” since the Rackspace sample code, docs and live API didn’t match each other. My secret: I actually guessed URLs in the browser to find the endpoints I needed. Swagger prevents that headache.
idratherbewriting.com: 10 realizations as I was creating my Swagger spec and Swagger UI
developer.mozilla.org: List of default Accept values