Problem

We wanted to come up with a way to share executable API specifications within engineering teams using revision control. A strict rule we adhere to when the building the system is "The Intern Test" -- that is, Lama2 API files must remain easy for interns to get used with minimal handholding from more experienced engineers. If it doesn't work for interns, then it is a bug in the system

System description

Presently, Lama2 is a API specification/execution language along with a nifty VSCode extension to simplify usage.

See examples to explore the syntax. The .l2 syntax is inspired by Markdown.

The tool is implemented in Golang, based on a formal grammar as a hand-crafted recursive descent parser. Moreover, the language supports Javascript blocks based on goja, using which API requests can be chained

The underlying language is presently tied to a VSCode extension for convenience.

Timeline

The prototype version of the project started more than a year ago at Hexmos, in the Python language with a simple regex implementation. Over time, it evolved into a tool strong enough to replace standard tools such as Postman/Insomnia within Hexmos. See blog post describing how Lama2 can accomplish such results.

So, before the Hackathon Lama2 could do all the basic http requests. We often found the system clunky and painful in the following ways on a day to day basis:

1. No code generation. We often wanted to convert l2 files into python and javascript code to be pasted into our projects.
2. No code prettification, especially larger JSON blocks within the file tended to become messy overtime
3. No autocomplete for environment variables. We'd often want to switch base URLs based on environment variables from l2.env files.
4. Other miscellaneous usability issues (detailed next section)

Hackathon progress

1. Code Generation from Lama2: Earlier we were not able to generate useful API request code snippets from Lama2's .l2 files. With the new code generation feature, we can generate API code in 18 languages (and 37 libraries). We use our own custom fork of httpsnippet library to accomplish this. We load up an httpsnippet bundle into a goja VM within our golang codebase to perform the conversion in the core component. In the frontend, the VSCode extension adds a new menu item called "Lama2: Generate Code Snippet" under which all languages and libraries can be accessed.
2. Autocomplete environment variables within l2 file: Earlier if we had to say, switch the base URL variable within l2 files, we had to look int l2.env and then manually make the change. We made changes to the VSCode extension so that there is a fast autocompletion of environment variables right from within VSCode.Find extension changes here: https://github.com/HexmosTech/Lama2Code/
3. JSON prettification within l2 file: Often we noticed that the l2 files become messy/disorganized when dealing with medium/large size JSON inputs. Made modifications to the golang core to support a new l2 -b targetFile option to enable JSON prettification. Tomorrow, we will add a VSCode UI hook to simplify the action.
4. *Request Examples from VSCode: * Earlier to find a sample template for a particular type of request (say multi-part POST), we'd have to goto documentation page. Now, we have a new option from VSCode called "Request Examples" which provides 9 different types of examples right at the user's fingertips. Users can immediately insert the template into their active editors with one click.
5. Get Remote Git URL for active l2 file: We often refer to .l2 files within code reviews. It is painful to fetch the URL to the particular API file. So, we implemented a new VSCode extension feature called "Get Remote Git URL" to generate direct link to the active l2 file.

State of completion

Overall, we implemented 5 new features within the Lama2 core and the extension improving overall usability of the system. To the best of our knowledge, the features are working find on all basic examples. However, one deficiency with certain implemetnations is the more nuanced handling of multi-staged (chained) API files. For example, for code generation, the correct behavior for a mult-staged file is more sophisticated than what we can effectively handle within the timeframe available. We will be thinking deeper into the multi-stage example, and improve our solutions overtime. From our experience, 9/10 files we have are for individual APIs, and the multi-stage edge case must be handled during further efforts.

Lama2: Plain-Text Powered REST API Client

About

Lama2 is a Plain-Text powered REST API client & manager built for serious engineering teams. Lama2 specifies the .l2 syntax for describing APIs, and implements a CLI to execute .l2 files. Engineers collaborate on .l2 files using version control. Lama2 integrates nicely with IDEs and text-editors as well. Think of Lama2 as Markdown for APIs.

Benefits

1. Plain-Text files: Store APIs in the Plain-Text .l2 API files. Simple and human-friendly syntax. Learn basics within minutes!
2. Simple CLI: Launch the CLI tool l2 on API files to make REST API requests.
3. Editor support: Invoke Lama2 from your favorite text editor or IDE. Helpful documentation and tool support to build editor extensions included.
4. Longevity & track-ability: Commit .l2 files to git or other version control for long life & change tracking.
5. Collaboration: Share API repo with teammates and colleagues to collaborate
6. Powerful chaining: Chain multiple l2 requests through embedded Javascript blocks
7. Documentation: Explore examples, how-tos, explanations, references, FAQ/RAQs, and diagrams. Documentation is a priority, so that you never have to get lost.
8. Extensibility: .l2 syntax is implemented as a recursive descent parser, based on a formal grammar. Dig into details and implement new syntax (ex: to support websockets)

> :bulb: Coming from Postman? Let Lama2 help you convert Postman data dumps into a nice Plain-Text Lama2 repo.

Terminal Demo: A POST request

VSCode Demo: The same POST request

Installation/Update

For Linux/MacOS systems, run the following command to either install or update Lama2:

curl -s https://hexmos.com/lama2/install.sh | bash -s

For Windows systems, run the following command on powershell as an Administrator to either install or update Lama2:

choco install lama2 --version=1.0.0 --force -y

Learn more about other installation methods from our docs.

(Optional) Import your collections from Postman

Follow guide to import your existing Postman collections into a Plain-Text Lama2 repository.

Self update

An easier way to update the binary for Linux/MacOS to latest release is through:

l2 -u

VSCode Extension

Find Lama2 for VSCode at the VSCode Marketplace. The extension requires the l2 command available (usually at /usr/local/bin/l2).

Design Philosophy

Lama2 takes inspiration from Markdown. Think of our approach as Markdown for APIs.

In particular, we strive to:

1. Delegate subtasks to mature and preferably open tools:
   1. API Collaboration - git
   2. API Organization - OS file system + IDEs
   3. API Editing - VSCode/IDEs
   4. API Requests - HTTPie (httpie-go, to be specific)
   5. Request Chaining - Embedded Javascript
2. Start a language formalization effort from the beginning (learning from Markdown history)
3. Keep language syntax simple
4. Invest into good documentation; however, ensure users can perform competently without referencing documentation as much as possible.
5. Strive to keep components decoupled

Community and Support

1. Full documentation @hexmos.com/lama2
2. Report issues and propose improvements at Github issues
3. Discuss with the community at Discord and Github Discussions