Collaborate on APIs for free, with Lama2, git and VSCode
Tags: api, postman, opensource, git
Published: 2023-01-05 10:29:05

When it comes to defining, testing, and sharing APIs within a team, many developers rely on tools like Postman and Insomnia. While these tools are powerful and widely used, they have some drawbacks. One major issue is that they can be expensive, especially if your team is large or if you need to use advanced features. In addition, these tools often require you to store your data in private clouds, which can raise concerns about security and control. Alternatively, there are some text-based flows that can be used for defining and testing APIs, but these are often limited to command-line interfaces (CLIs) or are tied to specific editors. This can make it difficult to use these tools in a collaborative setting, or to integrate them with other tools in your workflow.

But there is a solution!

- By using [Lama2](https://hexmos.com/lama2) in combination with Git and Visual Studio Code, you can define, test, and share APIs within your team without incurring the costs and limitations of other tools.
- Lama2 is a simple and easy-to-learn language for defining APIs, and it can be invoked from within Visual Studio Code GUI through an extension.
- Lama2 can import data from tools like Postman, making it easy to migrate to this new workflow.
- Most teams already use Git, to track changes to your code and collaborate with others, and Visual Studio Code integrates seamlessly with Git
- These tools provide a powerful and flexible workflow for defining, testing, and sharing APIs within your team, all for free.

Follow along the tutorial to find out learn more about the solution.

## A step-by-step tutorial for using Lama2, Git and VSCode for API collaboration

### 1. Prepare `git` repository

Within your teams, there are multiple ways of incorporating *Lama2*. One is to have a team level `APIHub` repository for all your projects in one place. Another is to have an `API` directory in each of your projects. At Hexmos, we use the former method, of having a central place for storing all our APIs. Either way, you need a `git` repository for collaboration.

For the sake for the tutorial, you may simply use a repository I have created for demonstration. Clone it with the following command:

```
git clone git@github.com:HexmosTech/Lama2Tutorial.git
```

The repository comes pre-loaded with data useful for demonstrating Lama2's features.

### 2. Install Lama2 and its VSCode extension

In Linux/Mac, run the following one-liner to get Lama2 CLI:

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

In Windows, you need [choco](https://chocolatey.org/). Run as **administrator**:

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

To verify installation, in the terminal type:

```
l2
```
**VSCode Extension installation:**

Open up VSCode, and then install the [extension](https://marketplace.visualstudio.com/items?itemName=hexmos.Lama2).

You can also install the extension by Pressing `Ctrl+P` and then pasting `ext install hexmos.Lama2`.

### 3. (Optional) Import Postman data

*Lama2* has the capability to import APIs from Postman into a simple file and directory structure. The step is optional, and if you do not have Postman data, skip to the next step.

#### 3.1 Access Settings

![Postman settings](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/r2nma891oveuivv6xxwz.png)

#### 3.2 Export data


![Export data](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rq54qd4cy8g5kkvggvy3.png)

**Note:** Although postman offers more selective exporting (collection, folder, request levels), Lama2 presently supports only the whole-data export depicted above.

#### 3.3 Convert to Lama2 repo

The `Lama2Tutorial` repo you cloned earlier contains a sample Postman dump, if you do not have a data dump of your own. Use the following command to obtain a Lama2 repo:

```
l2 -p Backup.postman_dump.json -l output
```

*Lama2* will ask for you to select an API environment from Postman. Pick `0`. 

![Environment prompt l2](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6dr346zijbf12gpr6uqj.png)

Within a minute or so, you'll see that *Lama2* has produced a plain-text version of your Postman data:

![Postman to Lama2 repository](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/g78g587bwf7evwk23itv.png)


### 4. Using Lama2 to execute APIs

As of now, there are two ways to execute `.l2` API files:

1. Through command line `l2 <api_file>`
2. Through the VSCode extension; Just press `Ctrl+Shift+P` and search for `Lama2: Execute current file`

![VSCode extension, run l2 file](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2dcbyubk88cfsefotzk7.png)

I recommend the VSCode extension for convenience. 

### 5. Introducing the Lama2 language: Examples

In this section, I'll introduce you to various types of requests in Lama2. All the samples being used here are available in the `examples` directory of the repository we clone in previous step.

#### GET request

```
GET
https://httpbin.org/get
```
Get [Source File](https://github.com/HexmosTech/Lama2/tree/main/examples/0000_sample_get.l2)

#### JSON POST request

One can dump the JSON body at the end of an `.l2` file to create a POST request:

```
POST
https://httpbin.org/post

{
    "a": "b",
    "c": "d"
}
```
Get [Source File](https://github.com/HexmosTech/Lama2/tree/main/examples/0002_sample_post.l2)

#### JSON POST in VarJSON format

Make a POST request with JSON body specified
as `key=value`. *Lama2* converts the input into
a corresponding JSON value `{"a": "b", "c": "d"}`. We call the `key=value` format *VarJSON*. This example produces an effect identical to the [previous one](#basic-json-post)

```
POST
https://httpbin.org/post

a=b
c=d
```
Get [Source File](https://github.com/HexmosTech/Lama2/tree/main/examples/0001_sample_post_varjson.l2)

#### Comments

One can start a comment anywhere in the file
with the `#` character.

```
#### Pound symbol signifies a comment
POST
https://httpbin.org/post

a=b # Comments may start at the end of lines as well
c=d

#### Comments work even after the payload
```
Get [Source File](https://github.com/HexmosTech/Lama2/tree/main/examples/0003_comment.l2)

#### Environment Variables: Switch base URL

Specify variables in `l2.env` and then load
them up in the API files. Presently, **the `l2.env` file should reside in the same directory as the `.l2` API file.**

**l2.env**

```
export LOCAL="http://localhost:8000"
export REMOTE="http://httpbin.org"
```

**env_example.l2**
```
POST
${REMOTE}/post

{
    "lorem": "ipsum"
}
```

Get [Source Files](https://github.com/HexmosTech/Lama2/tree/main/examples/0004_env_switch_root)

#### Headers

Use `key:value` format to specify headers.

Specify strings for key/value in three ways:

1. Double quoted (`"hello"`)
1. Single quoted (`'hello'`)
1. Unquoted (`hello`)

```
POST 
https://httpbin.org/post

# HEADERS
X-Parse-Application-Id:'helloworld'
X-Parse-REST-API-Key:"byeworld"

# DATA
a="b"  # double-quoted string
'c'=d  # single-quoted & unquoted strings
```

Get [Source File](https://github.com/HexmosTech/Lama2/tree/main/examples/0005_headers_simple.l2)

**Note: ** The data section may appear *before* headers as well (see below)
```
POST 
https://httpbin.org/post


# DATA
a="b"  # double-quoted string
'c'=d  # single-quoted & unquoted strings

# HEADERS
X-Parse-Application-Id:'helloworld'
X-Parse-REST-API-Key:"byeworld"
```


#### Send cookies in header

Headers represent cookies in *Lama2*. Just specify cookie key value pairs separated by `=` within the header value as shown.
```
POST 
https://httpbin.org/post

# HEADERS
Cookie:"sessionid=foo;another-cookie=bar"

# DATA
hello=world
```
Get [Source File](https://github.com/HexmosTech/Lama2/tree/main/examples/0006_cookies.l2)

#### Fill forms & attach files with MULTIPART

Use the `MULTIPART` keyword after the HTTP verb to enable forms and file attachments.

The data section may contain any number of form inputs using the `key=value` syntax.

Following the data section, one can specifyany number of files in the form of `<field_name>@<file_path>`. The file path isrelative to the API file.

```
POST
MULTIPART
http://httpbin.org/post

'X-Parse-Application-Id':hello 
X-Parse-REST-API-Key:"world"

# DATA
first=second

# FILES
myfile@./image.jpeg
```
Get [Source Files](https://github.com/HexmosTech/Lama2/tree/main/examples/0007_multipart_file)

#### Image as Base64 encoded JSON field

We can embed images (or other files) as base64 strings in JSON using *Lama2*.

First, we define a `PHOTO` variable, loaded up with the results of the `base64` command.

**l2.env**

```
export PHOTO=`base64 image.jpeg`
```

Next, we refer to the `PHOTO` variable inthe API file. Pay special attention to the quoting mechanism `"'{PHOTO}'"`. 


**Warning:** **The quoting must look exactly as shown in the following template for the request to work correctly.**

**base64_embed.l2**

```
POST
http://httpbin.org/post

{
	"imageb64_field": "'${PHOTO}'",
}
```
Get [Source Files](https://github.com/HexmosTech/Lama2/tree/main/examples/0008_base64_image)

### 6. Best Practices, Tips & Tricks

#### Mandate attaching `.l2` files in code reviews

One of the challenges with code reviews is understanding how the API interfaces are evolving. At Hexmos, we add references to relevant `.l2` API files in each Merge Request. This helps the reviewer understand the change faster, there is a good record of what the change was about, and it serves to catch mistakes in interfaces early on.


![Attaching l2 files to code reviews](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zs6vh0oeq6inpwvpmafo.png)

#### Use `git blame` to find people who've worked on the API

Due to the integration with git, it is usually super easy to find contributors to the definition of a particular specification. Similarly, one can use the file history to see how it has evolved over time.


![Use git blame to find API contributors](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6b399zz3pw0btf0qomab.png)

#### Specify Inputs/Outputs as comments in the API file

We have found over time that specifying some internal details about the API in the file helps with understanding. We tend to record the inputs, what data sources does it affect, and what are the consequences of running the API.


![Describe API I/O through comments](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/je3yb71put7rmr27fxz1.png)

#### VSCode works wonderfully for API navigation, searching and organisation

VSCode works as an excellent companion for jumping into API definitions, searching for particular keywords in APIs and organising files into folders. One can invent one's own custom tagging scheme as well, as comments in the API files.


![Use VSCode as API navigator/organizer](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/a0q72ylh12de2la8yy0u.png)

### Conclusion

In summary, using Lama2 in combination with Git and Visual Studio Code provides a powerful and flexible workflow for defining, testing, and sharing APIs within your team. By importing data from tools like Postman, you can easily migrate to this new workflow and take advantage of the benefits it offers. With Lama2, you can create and edit your API definitions in a simple and intuitive language, and with Git and VSCode, you can collaborate with your team and track changes to your code. Best of all, this workflow is completely free, making it an excellent choice for teams on a budget.

We hope that you have found this tutorial helpful and that you will consider using Lama2 in your own API development projects. If you have any feedback or suggestions, or if you would like to contribute to the project, we encourage you to visit the project repository on GitHub at https://github.com/HexmosTech/Lama2. There, you can file issues, submit pull requests, and join the community of developers who are helping to make Lama2 even better.

Thank you for following along with this tutorial, and we hope you have a great experience using Lama2!