Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by atomicnature on Sunday January 01, 2023 @09:06AM
(#34206334)
Hey everyone,
I've been working on publishing *Lama2*, a Plain-Text Powered REST API Client for Teams, for the past few months. Initial work on Lama2 started after my dissatisfaction with existing tools such as Postman/Insomnia. I wanted a text-powered and git-friendly system with a lightweight GUI layer on top so that I could onboard beginners/newcomers quickly into my team while also maintaining control over data. Today, we use Lama2 extensively internal to Hexmos; almost every internal code review tends to have a `.l2` API file attached now. It has worked great for us. More about the approach with Lama2 below.
The story begins more than a year back, when our team at Hexmos wanted to collaborate on APIs in a simple and straightforward way.
Our engineering infrastructure is split into dozens of self-contained software services. We deal with 100s of internal APIs, and so felt a need for a robust workflow for defining, sharing and updating APIs within our teams.
Traditional solutions such as Postman/Insomnia implement the collaboration features within their applications, and also tend to charge a fee for collaboration. We felt using git is the right way to collaborate on APIs, rather than any custom built solution. So, in a matter of 2 days we got a regex-based prototype DSL language to store API files.
Lots of issues cropped up over time, but we kept making improvements to Lama2 as needs arose. We accumulated 100s of API files over time. Then, we decided that the tool deserves to be out there, benefiting teams that want to collaborate on APIs over git. So, to make it happen, first we invested into formalising the grammar, and implementing the DSL as a hand-written recursive descent parser. Then we invested into helpful documentation, demos and so on. Once we had the basics, we released Lama2 into the world.
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by atomicnature on Monday January 02, 2023 @03:35AM
(#34215715)
1. hurl.dev seems to do a lot more, with a focus on testing/CI/CD. I am focusing more on simplifying the request/response flow alone. I primarily care about interactive usage. IMHO, tests and CI/CD are better done through project languages, such as Python.
2. hurl.dev seems to focus less on team/collaboration aspect. For me, the first and foremost usecase is onboarding new teammates, ability to link APIs in code reviews, finding diffs in API, etc. Ease of use is paramount. So, I have developed a VSCode extension (https://marketplace.visualstudio.com/items?itemName=hexmos.L...), and want to focus on developing integrations with various other editors as well.
3. Another agenda I have is to develop good documentation and communication around a Plain-Text based API workflow for teams. I believe explicitly explaining how a Plain-Text + Editor GUI workflow can remove the need for expensive solutions is an important point.
4. I believe the syntax for hurl.dev is not exactly "memory-friendly". Example:
HTTP/1.1 200
[Captures]
csrf_token: xpath
"string(//meta[@name='_csrf_token']/@content)"
# Do login!
POST https://example.org/login?user=toto&password=1234
X-CSRF-TOKEN: {{csrf_token}}
I am resolved to keep the syntax simple/readable first and foremost so that I can onboard new people into the language real fast, with less dependency on repeatedly referring to documentation.
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by jicea on Monday January 02, 2023 @12:22PM
(#34220610)
Hi, maintainer of Hurl here [1]! We try to make a really simple syntax while enabling passing data between requests. I find Hurl syntax clean, but beauty seems to be in the eye of the beholder... Good luck with Lama2!
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by atomicnature on Monday January 02, 2023 @12:36PM
(#34220834)
Apologies if it came across as an attack -- emphasis on "I believe" :)
In text markup as well, there exists a wide range of options to choose from. MD/WikiText/AsciiDoc/reST/BBCode etc. Each seems to be optimised for slightly different contexts.
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by jicea on Monday January 02, 2023 @01:49PM
(#34221944)
No offense! I really think there’s a strong need for a « Mardowned » HTTP format, for documentation, tests etc… Lots of good solutions, Lama2 included.
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by user3939382 on Tuesday January 03, 2023 @02:19AM
(#34228769)
The JetBrains IDEs have a similar feature (text based REST client). It’s got a ways to go but has also come a long way, you can see from the patterns in release notes it’s a focus for JetBrains. I can’t wait for it to mature. For this purpose, text configs >>> a GUI like Postman. IMHO even more so when tightly integrated with the IDE/debugger/etc.
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by atomicnature on Tuesday January 03, 2023 @02:56AM
(#34228982)
JetBrains - good mention, it's a move in the right direction. I too am eager to see this space mature.
I am strongly in favor of text config + lightweight GUI in multiple editors/IDEs; that's the underlying idea with Lama2. Just as in the document markup space, there is room for multiple solutions with slightly different application areas here as well.
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by sa46 on Tuesday January 03, 2023 @02:26PM
(#34236665)
I’ve been meaning to start using JetBrains http files as integration tests with their recent free-as-in-beer jar [1]. There was also an open-source Go implementation floating around that I can’t find.
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by atomicnature on Tuesday January 03, 2023 @02:58AM
(#34228992)
Yes, I've seen the documentation for this, although I personally am not a emacs user, neither are my team mates.
With Lama2, my approach is to separate the language from the various editor extensions. Keep the language simple/lean and then build extensions/integrations to different text editors & IDEs on top of the core.
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by atomicnature on Tuesday January 03, 2023 @02:14PM
(#34236469)
Lama2 probably will never have as many options/complexity as this extension. For the following purpose.
If I add an intern into my team, I want them to "get" what's going on with APIs without many reference docs. So it has to pass real "intern tests".
Second difference is: I want to keep the "language" and "extension" utterly separate. In fact, I want `l2` support in multiple editors; VSCode is just a start.
Third, I have a rudimentary Postman import, which preserves original hierarchy/organization. My focus is to get the basic features of Postman with similar ease of use, on top of a lightweight UI. (maybe 20% of Postman's features; not more)
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by atomicnature on Tuesday January 03, 2023 @02:10PM
(#34236413)
Not yet, for the following reason.
I do not want to import xpath/jsonpath syntax as is.
My goal is: if a new intern joins my team, I don't want to send them 3 reference docs (for lama2, xpath and jsonpath) just so they understand what's going on with APIs :)
So I am still musing of ways to get some sort of chaining, without complicating the syntax. Implementation is not the problem, but the right level of complexity (a.k.a does this pass the "intern test"?)
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by ptrthomas on Thursday January 05, 2023 @09:13PM
(#34270075)
Congrats on the launch ! I'm the lead dev of Karate[1] and was wondering if you had come across it. I strongly agree with you that collaboration should be via Git and the IDE[2] and that traditional solutions fall short. I hope Karate's syntax passes your "memory friendly" test :) We get regular feedback is that it is easy to read and even non-programmers can pick it up.
One thing I feel we do really well is chaining of HTTP requests. And we have plugins for IntelliJ[3] and Visual Studio Code[4].
Maintaining a tool like this as open-source is a big effort, all the best !
Re:Show HN: Lama2 - Plain-Text Powered REST API Client for T...
by atomicnature on Friday January 06, 2023 @09:03AM
(#34274635)
Hi :) I had seen Karate mentioned in some of the docs, but didn't go into it in depth, at the time. Your solution to the chaining problem looks simple enough; I'll give it a try once I have an opportunity.
I've been working on publishing *Lama2*, a Plain-Text Powered REST API Client for Teams, for the past few months. Initial work on Lama2 started after my dissatisfaction with existing tools such as Postman/Insomnia. I wanted a text-powered and git-friendly system with a lightweight GUI layer on top so that I could onboard beginners/newcomers quickly into my team while also maintaining control over data. Today, we use Lama2 extensively internal to Hexmos; almost every internal code review tends to have a `.l2` API file attached now. It has worked great for us. More about the approach with Lama2 below.
TLDR:
- Approach: "Markdown for APIs" (Design philosophy - https://hexmos.com/lama2/reference/philosophy.html)
- Store APIs in plain-text files in human friendly syntax. (Examples - https://hexmos.com/lama2/tutorials/examples.html)
- Simple CLI to execute API files
- VSCode extension to launch requests right from within your editor
- Collaborate with team over git
- Good documentation + Extensibility
- Import from Postman into Lama2 files
- Fun Implementation :) Hand-crafted recursive descent parser in Golang; integrated flexible JSON parser
Links:
- Documentation site: https://hexmos.com/lama2
- Github: https://github.com/HexmosTech/Lama2
Background story:
The story begins more than a year back, when our team at Hexmos wanted to collaborate on APIs in a simple and straightforward way.
Our engineering infrastructure is split into dozens of self-contained software services. We deal with 100s of internal APIs, and so felt a need for a robust workflow for defining, sharing and updating APIs within our teams.
Traditional solutions such as Postman/Insomnia implement the collaboration features within their applications, and also tend to charge a fee for collaboration. We felt using git is the right way to collaborate on APIs, rather than any custom built solution. So, in a matter of 2 days we got a regex-based prototype DSL language to store API files.
Lots of issues cropped up over time, but we kept making improvements to Lama2 as needs arose. We accumulated 100s of API files over time. Then, we decided that the tool deserves to be out there, benefiting teams that want to collaborate on APIs over git. So, to make it happen, first we invested into formalising the grammar, and implementing the DSL as a hand-written recursive descent parser. Then we invested into helpful documentation, demos and so on. Once we had the basics, we released Lama2 into the world.
Future tasks:
- Create human-friendly syntax for specifying websocket APIs, basic testing, etc
- Integration with more editors + deeper/richer integration
Any suggestions/criticism/feedback welcome :)
2. hurl.dev seems to focus less on team/collaboration aspect. For me, the first and foremost usecase is onboarding new teammates, ability to link APIs in code reviews, finding diffs in API, etc. Ease of use is paramount. So, I have developed a VSCode extension (https://marketplace.visualstudio.com/items?itemName=hexmos.L...), and want to focus on developing integrations with various other editors as well.
3. Another agenda I have is to develop good documentation and communication around a Plain-Text based API workflow for teams. I believe explicitly explaining how a Plain-Text + Editor GUI workflow can remove the need for expensive solutions is an important point.
4. I believe the syntax for hurl.dev is not exactly "memory-friendly". Example:
I am resolved to keep the syntax simple/readable first and foremost so that I can onboard new people into the language real fast, with less dependency on repeatedly referring to documentation.[1] https://hurl.dev
In text markup as well, there exists a wide range of options to choose from. MD/WikiText/AsciiDoc/reST/BBCode etc. Each seems to be optimised for slightly different contexts.
I am strongly in favor of text config + lightweight GUI in multiple editors/IDEs; that's the underlying idea with Lama2. Just as in the document markup space, there is room for multiple solutions with slightly different application areas here as well.
With Lama2, my approach is to separate the language from the various editor extensions. Keep the language simple/lean and then build extensions/integrations to different text editors & IDEs on top of the core.
If I add an intern into my team, I want them to "get" what's going on with APIs without many reference docs. So it has to pass real "intern tests".
Second difference is: I want to keep the "language" and "extension" utterly separate. In fact, I want `l2` support in multiple editors; VSCode is just a start.
Third, I have a rudimentary Postman import, which preserves original hierarchy/organization. My focus is to get the basic features of Postman with similar ease of use, on top of a lightweight UI. (maybe 20% of Postman's features; not more)
I do not want to import xpath/jsonpath syntax as is.
My goal is: if a new intern joins my team, I don't want to send them 3 reference docs (for lama2, xpath and jsonpath) just so they understand what's going on with APIs :)
So I am still musing of ways to get some sort of chaining, without complicating the syntax. Implementation is not the problem, but the right level of complexity (a.k.a does this pass the "intern test"?)
One thing I feel we do really well is chaining of HTTP requests. And we have plugins for IntelliJ[3] and Visual Studio Code[4].
Maintaining a tool like this as open-source is a big effort, all the best !
[1] https://github.com/karatelabs/karate
[2] https://www.karatelabs.io/first-class-citizens
[3] https://plugins.jetbrains.com/plugin/19232-karate
[4] https://marketplace.visualstudio.com/items?itemName=karatela...
Plugins - both the extensions look great!
Thanks for your thoughtful response with context.