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 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. 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.
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
3.2 Export data
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.
Within a minute or so, you'll see that Lama2 has produced a plain-text version of your Postman data:
4. Using Lama2 to execute APIs
As of now, there are two ways to execute .l2 API files:
- Through command line
l2 <api_file> - Through the VSCode extension; Just press
Ctrl+Shift+Pand search forLama2: Execute current file
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
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
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
POST
https://httpbin.org/post
a=b
c=d
Get Source File
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
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
Headers
Use key:value format to specify headers.
Specify strings for key/value in three ways:
- Double quoted (
"hello") - Single quoted (
'hello') - 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
*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
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
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
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.
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.
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.
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.
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!
Top comments (1)
This is really extensive tutorial and documentation . Thanks!!