hexmostech / lama2

Free, Lightweight & Collaborative API Client

Lama2: Free, Lightweight & Collaborative API Client

Quick Links: Installation | Demo | Full Documentation

Note The frontend part of the Lama2 project lives in Lama2Code. The extension tends to be updated along with the Lama2 core in this repo.

The Problem

Most engineering teams have trouble collaborating on APIs or end up paying too much for Postman/Insomnia. Our 100% FOSS product Lama2 helps your team collaborate on APIs for free based on git, so that you can save money and avoid friction.

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. Code generation: Convert l2 API definitions into your preferred language/library, be it Python, Javascript, Java or many other options.
7. Powerful chaining: Chain multiple l2 requests through embedded Javascript blocks
8. Documentation: Explore examples, how-tos, explanations, references, FAQ/RAQs, and diagrams. Documentation is a priority, so that you never have to get lost.
9. 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)

💡 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

Acknowledgements

1. The excellent VSCode ecosystem helping us develop our VSCode extension
2. httpie-go: A golang version of httpie which we have forked and integrated with Lama2. Source
3. httpsnippet: A HAR Request to multi-language converter; we use a custom fork of httpsnippet for code generation from l2 files.
4. goja: A pure golang based JS interpreter with great, correct implementation of ECMA5. We use goja for JS processor blocks in multi-stage API files.

lama2's Issues

Control verbosity from the extension request

Trailing comment after JSON causes a syntax error

Postman collections to `.l2` converter

Postman data can be exported to various formats in static form. Insomnia too, has similar features.

It'll be useful to have automated conversion from collections -> a directory of .l2 files ready to be committed.

get "tar: Option --overwrite is not supported" on macos install

I'm using the command:

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

and getting the following error message in the end:

tar: Option --overwrite is not supported
Usage:
  List:    tar -tf <archive-filename>
  Extract: tar -xf <archive-filename>
  Create:  tar -cf <archive-filename> [filenames...]
  Help:    tar --help
mv: rename /tmp/l2 to /usr/local/bin/l2: No such file or directory

The os version: macos Ventura version 13.1

Generate Code Snippet gives junk values in clipboard if l2.env file is not found in the present/parent directories.

�[90m9:19PM�[0m �[32mINF�[0m Didn't find l2.env in the API directory �[36mType=�[0mPreprocess
const url = 'http://localhost:8000/polls/alldata';
const options = {method: 'get'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

How to make use of variable to remember the response and use it in subsequence command?

For application using JWT token this is the typical use case, like this in my current curl script:

TOKEN=$(curl   -d '{"email": "[email protected]", "pass": "hello"}' -H 'Content-Type: application/json'  http://localhost:3210/rpc/login | jq -r '.token')

curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" http://localhost:3210/user_articles?select=title

The first line gets the token from the response and then use the token to GET the result from the second line request.

Export l2 file into cURL, Python, JS, etc

It'll be super handy to have an option to generate Python/JS/Other code from .l2 specifications.

curlconverter seems like a nice JS project which can generate code in multiple languages, given a curl input. So, then, the subproblems become:

1. Create cURL from .l2
2. Use goja VM to load curlconverter
3. Pass the new curl command to curlconverter, to get code in various languages
4. Add UI support in VSCode extension

Investigate MULTIPART file attachments

With the changes related to l2config.env, I think MULTIPART attachments have gone broken. The MULTIPART attachment path must always be calculated relative the relevant .l2 file.

Moreover, in the environment loading logic, we seem to be making an error, that is chdir, load up env, chdir, go on parsing, making request, etc. The second chdir probably should happen as the last action.

@lovestaco

Update Docs for the Windows Manual Install

https://hexmos.com/lama2/tutorials/installation.html#manual-install

`.l2` Syntax Highlighting across multiple editors/IDEs

We need syntax highlighters for .l2 syntax. If you have experience in the area, please contact us.

From my limited research, iro4cli seems like a tool capable of generating multiple editor syntax format targets.

Windows Install Failed

choco -v

2.2.2
PS C:\WINDOWS\system32> choco install lama2 --version=1.0.0 --force -y
Chocolatey v2.2.2
3 validations performed. 2 success(es), 1 warning(s), and 0 error(s).

Validation Warnings:

• A pending system reboot request has been detected, however, this is
  being ignored due to the current Chocolatey configuration. If you
  want to halt when this occurs, then either set the global feature
  using:
  choco feature enable --name="exitOnRebootDetected"
  or pass the option --exit-when-reboot-detected.

Installing the following packages:
lama2
By installing, you accept licenses for the packages.
lama2 not installed. The package was not found with the source(s) listed.
Source(s): 'https://community.chocolatey.org/api/v2/'
NOTE: When you specify explicit sources, it overrides default sources.
If the package version is a prerelease and you didn't specify --pre,
the package may not be found.
Version was specified as '1.0.0'. It is possible that version
does not exist for 'lama2' at the source specified.
Please see https://docs.chocolatey.org/en-us/troubleshooting for more
assistance.

Chocolatey installed 0/1 packages. 1 packages failed.
See the log for details (C:\ProgramData\chocolatey\logs\chocolatey.log).

Failures

• lama2 - lama2 not installed. The package was not found with the source(s) listed.
  Source(s): 'https://community.chocolatey.org/api/v2/'
  NOTE: When you specify explicit sources, it overrides default sources.
  If the package version is a prerelease and you didn't specify --pre,
  the package may not be found.
  Version was specified as '1.0.0'. It is possible that version
  does not exist for 'lama2' at the source specified.
  Please see https://docs.chocolatey.org/en-us/troubleshooting for more
  assistance.

Enjoy using Chocolatey? Explore more amazing features to take your
experience to the next level at
https://chocolatey.org/compare

Use a Go-based HTTP Client or lib instead of HTTPie ?

I love HTTPie , but since Python is a big dependency and since Lama2 is developed in GO , are there any plan to to use Go-Based httpclient or lib?eg:
https://github.com/nojima/httpie-go

Windows & WSL Platform Support

Lama2 support in pure Windows and WSL contexts requires an end to end testing and calibration:

1. Modify install.sh script to support Windows & WSL
2. Update mechanism -u
3. HexmosTech/Lama2Code support both in pure Windows and WSL

Build Editor/IDE Extensions for Lama2

According to the Stackoverflow survey, the following seem like some important platforms that may benefit Lama2 integration:

1. Vim/NeoVIM
2. Jetbrains Intellij, Rider, Pycharm, GoLand, CLion, etc
3. Emacs
4. Visual Studio
5. Sublime Text
6. XCode

Any help with supporting these platforms is appreciated. The documentation contains points on how to build Editor/IDE extensions.For discussions/support, post in the thread, and join our Discord server.

Prettify command switch for `l2` CLI

The prototype version of l2 had an option to prettify/standardize .l2 files. The previous version depended entirely on regular expressions for identifying the various pieces of input (verb, url, headers, json/varjson). It is not entirely clear, what is the correct approach to implementing a prettification algorithm. Hence, the task involves two phases:

1. Specify the approach/algorithm
2. Implement the algorithm

Note that, in the present version, it is almost trivial to implement JSON prettification. The difficulty is in dealing with arbitrary input order (say URL comes before Verb).

Autocomplete variables in VSCode extension

We tend to have variables for remote/local hostname, and presently it is cumbersome to switch between the various values. Build an autocomplete for variables; fetch values from l2.env and if possible from JS blocks.

Show request headers in the headers tab

Presently only the Response headers seem to appear

Add support for `x-www-form-urlencoded`

The following request cannot be made presently using Lama2:

curl --request POST \
  --url http://localhost:3000/oauth/token \
  --header 'Authorization: Basic YXBwbGljYXRpb246c2VjcmV0' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=password \
  --data username=pedroetb \
  --data password=password

We have the MULTIPART keyword, but that is not exactly x-www-form-urlencoded. The difference between these two options can be found at SO

Maybe we could have something as simple as:

POST
FORM
http://xyz

a=b
c=d

Easy way to URL encode parameters

Example file:

GET
${LOCAL_COORD}/api/request-pwd/[email protected]

In this case + is a special character which is part of the email value. It is not being interpreted correctly at backend.

However, if I URL encode the + character as follows, it works as expected:

${LOCAL_COORD}/api/request-pwd/?email=qp0co2%2Bc5yyclrbbhrt3e%40sharklasers.com

Integer variable expansion fails in JSON body

${uid} expansion fails in the above example. If we include quotes around the variable ("${uid}"), variable expansion works as expected. However, the former case is supposed to work.

Re-run file/request button

Sometimes it is easier to launch a request through a button, rather than the command shell.