ALPS Unified Utility

Open-Sourcing a personal API Design tool

Over the last several months, I’ve been talking (and writing) about a small command-line utility app that I created to help me design/build my APIs: the app is called “unified” and is a very small app written in NodeJS.

This utility converts valid ALPS API description documents into valid API definition documents like OpenAPI, ProtoBuf, Schema Definition Language, AsyncAPI, and even WSDL. I like using this tool because it allows me to focus on a clean design before having to deal with the details of converting that design into a viable implementation.

Design First with ALPS

I talk about the power and value of this “Design-first” approach to APIs in my talk “GraphQL, gRPC, and REST. Oh, My!”. The message of the talk is to stop using OpenAPI and other formats as your design language and, instead, use a language/format that allows you to better focus on design elements first and implementaiton details later. In my talk, I advocate using an API description format called ALPS (Application-Level Profile Semantics). This format was created by myself along with Leonard Richardson and Mark Foster.

The ALPS format was design to help you focus on describing the problem, not the solution. That means things like URLs, status codes, and HTTP methods are not part of the document. Instead things like actions (read, write, submit, approve, etc.) and data properties (familyName, givenName, etc.) are included. Below is a simple ALPS document to show you what I mean:

alps:

  version: '1.0'

  doc:

    value: 'Simple Todo list example'

  descriptor:

    # these are the data elements

    - id: id

      type: semantic

      text: storage id of todo item

    - id: body

      type: semantic

      text: content of todo item

    # these are the storage objects

    - id: todoItem

      type: group

      text: todo item

      descriptor:

      - href: '#id'

      - href: '#body'

    # these are the operations

    - id: todoList

      type: safe

      rt: todoItem

      text: return list of todo items

    - id: todoAdd

      type: unsafe

      rt: todoItem

      text: create a new todo item

      descriptor:

      - href: '#todoItem'

    - id: todoRemove

      type: idempotent

      tags: delete

      rt: todoItem

      text: remove a single todo item

      descriptor:
      - href: '#id'

The above information, along with a dash of metadata, is all that is needed to generate valid API definition documents for implementations in GraphQL, gRPC, REST, MQTT, SOAP, and others.

Open Sourcing UNIFIED

As more and more people are expressing interest in my personal demo project, I’ve been getting helpful feedback and contributions for the utility. For that reason, I’ve opened up a stand-alone public repository on github for the “unified” utility. The tool is still pretty rough and I’d love to hear from others on how it can be improved and used as part of a robust API design & build toolchain.

Feel free to check it out, download & install it, and tell me what you think. Over the next few weeks I’ll start to share examples of how I use it in my own API process, too.

I’ll probably add a short video to Youtube soon, too. To get an alert when I post my video, be sure to subscribe to my channel.

— @mamund