Building a Microservice in Perl (Part 1): Designing the API
A brief description of microservices, then jumping into defining one with OpenAPI.
Join the DZone community and get the full member experience.Join For Free
A microservice can be thought of as the distributed computing implementation of the Unix philosophy of "Do one thing and do it well." Usually modeled around specific business domains, a well-designed set of microservices each have their own lifecycle and communicate with each other and with consuming applications via technology-agnostic protocols like HTTP.
Because of this, a microservice may be implemented using whatever is the best programming language, database, or other environment to fit the job. Perl can be an excellent choice for development because of its strengths as a battle-tested, expressive multi-paradigm language with a broad open-source library of modules.
In this series of articles, we'll be using Perl, the Mojolicious web framework, and the OpenAPI (formerly Swagger) specification for describing web services to develop an example microservice that adheres to the REST architectural style for communication over HTTP. Some knowledge of Perl and web development is assumed, and we'll be linking to supporting documentation and literature as we go.
In a full microservices implementation, we would start by modeling the business domains being serviced and the explicit boundaries between them. For the purposes of this series, we are limiting ourselves to developing only one microservice with a trivial purpose-a toy, if you will. This service will act as a simple dictionary allowing consumers to both query for the definitions of words as well as add new entries.
We could envision a variety of consumers: a web front-end, a mobile app, maybe even SMS text messaging. The key is that the design of our application programming interface (API) should not dictate the implementation or lifecycle of any of these consumers, and it should be easy for their developers to understand its specification.
To that end, we turn to OpenAPI, which gives both our microservice and its consumers an unambiguous machine-readable description of the interface without the need for additional code or documentation. And as we'll see later, we'll use that very same specification to drive our web framework to produce HTTP routes that accept valid input and produce valid output.
A full OpenAPI document can be written in either JSON or YAML format, but it must ultimately be able to be represented in both formats, so there are some limitations described in the spec. Here's the OpenAPI document for our dictionary microservice in YAML:
(I worked on this in the free online Swagger Editor, which checks your syntax, previews what API documentation might look like, and offers suggestions if it finds errors in your document.)
Most of the above should be fairly self-explanatory to any web developer, and you can check the OpenAPI specification for required and optional fields and their allowed values. The only odd field listed is
x-mojo-to; we'll be using the Mojolicious::Plugin::OpenAPI module to read that field when generating routes to controllers in the Mojolicious web framework.
In the next installment, we'll actually be writing some Perl by building our Mojo application and tests.
Published at DZone with permission of Mark Gardner, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.