Building a Microservice in Perl (Part 1): Designing the API

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:

openapi: 3.0.3

info:

  title: Dictionary

  description: The PhoenixTrap.com dictionary microservice

  version: 1.0.0

  license:

    name: Artistic License 2.0

    url: https://www.perlfoundation.org/artistic-license-20.html

paths:

  /health:

    get:

      summary: Check if this service is online

      x-mojo-to: monitoring#heartbeat

      responses:

        200:

          description: All systems operational

          content:

            application/json:

              schema:

                type: object

        500:

          description: Something is wrong

  /word/{word}:

    get:

      summary: Get the definition of a word

      x-mojo-to: word#define

      parameters:

      - $ref: '#/components/parameters/word'

      responses:

        200:

          description: Found word

          content:

            application/json:

              schema:

                type: string

        404:

          description: Could not find word

    post:

      summary: Add or replace the definition of a word

      x-mojo-to: word#save

      parameters:

      - $ref: '#/components/parameters/word'

      requestBody:

        description: Definition of a word

        required: true

        content:

          application/x-www-form-urlencoded:

            schema:

              type: object

              properties:

                definition:

                  type: string

      responses:

        200:

          description: Word saved

    delete:

      summary: Delete an entry from the dictionary

      x-mojo-to: word#remove

      parameters:

      - $ref: '#/components/parameters/word'

      responses:

        200:

          description: Word deleted

components:

  parameters:

    word:

      description: A word in the dictionary

      in: path

      name: word

      required: true

      schema:

        type: string

(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.