--- type: "article" title: "ALPS Unified Utility" summary: "Open-Sourcing a personal API Design tool" newsletter: "Signals from Our Futures Past" newsletter_handle: "mamund" newsletter_url: "https://usecommune.com/n/mamund" author: "Mike Amundsen (@mamund)" published: "2020-11-21T23:05:38.065Z" canonical_url: "https://usecommune.com/n/mamund/a/alps-unified-utility" markdown_url: "https://usecommune.com/n/mamund/a/alps-unified-utility.md" chat_url: "https://usecommune.com/n/mamund/a/alps-unified-utility/chat" source_url: "https://mamund.substack.com/p/alps-unified-utility" body_source: "imported" likes: 0 replies: 0 body_words: 597 --- # ALPS Unified Utility 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](http://alps.io) API description documents into valid API definition documents like [OpenAPI](https://www.openapis.org/), [ProtoBuf](https://developers.google.com/protocol-buffers/docs/reference/proto3-spec), [Schema Definition Language](https://www.prisma.io/blog/graphql-sdl-schema-definition-language-6755bcb9ce51), [AsyncAPI](https://www.asyncapi.com/), and even [WSDL](https://www.w3.org/TR/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!](http://amundsen.com/talks/2020-04-goto-unified/)”. 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](http://alps.io/spec) (Application-Level Profile Semantics). This format was created by myself along with [Leonard Richardson](https://twitter.com/leonardr) and [Mark Foster](https://twitter.com/fosrias). 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](https://github.com/mamund/alps-unified) 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](https://www.youtube.com/mamund). — [@mamund](http://twitter.com/mamund) *** ## Discussion No replies yet.