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
