Update docs

cedric05 · Oct 20, 2023 · 4d9db4f · 4d9db4f
1 parent 9519c4e
commit 4d9db4f
Show file tree

Hide file tree

Showing 9 changed files with 326 additions and 248 deletions.
diff --git a/blog/2022-12-15-dothttp-extensions-1.0.0.md b/blog/2022-12-15-dothttp-extensions-1.0.0.md
@@ -1,26 +1,27 @@
 ---
-title: dothttp-runner 1.0.0
-author: prasanth
+title: Version 1.0.0 of dothttp-runner
+author: Prasanth
 author_url: https://github.com/cedric05
 tags: [dothttp-runner, vscode]
-description: extension release update.
+description: An update on the extension release.
 hide_table_of_contents: false
 ---
 
+We are thrilled to announce the official release of dothttp-runner 1.0.0, marking a significant milestone since its initial introduction in February 2021. Over the past few months, our primary focus has been on addressing various bugs, and we believe the time has come to reach the 1.0 milestone.
 
-This is our first ever 1.0 release since its first introduced (Feb 2021). For past couple of months updates mainly focuses on fixing bugs and we feel now is the time to hit 1.0. 
+As the sole developer and maintainer of this project, I take great pride in its progress, even though our user base remains modest, with fewer than 10 users. In my previous role, I was responsible for managing 10-20 microservices, each with its own set of APIs. Unfortunately, there were no dedicated clients or SDKs available to interact with these APIs. Using tools like curl was challenging due to the lack of convenient features for saving, updating, running, and sending requests. While Postman is widely used, I found it to be less developer-friendly and resource-intensive, making it less than ideal for my needs. This led to the creation of dothttp-runner, a tool designed to simplify and enhance the experience of working with HTTP requests, placing a strong emphasis on developer-friendliness.
 
-As a sole developer, i feel little proud of this product although adoption is little less. During my last job, I had work 10-20 microservices, each having its own apis. There is no client or sdk to interact with apis. Its hard to use curl as it is not easy to save or update. Postman is there (widely used) but i hated as its not dev friendly (hate switching multiple tabs and too many tabs). It also consumes huge cpu and memory. I started to built this product, solely to save and resue and dev friendly. These are the principles i have in mind.
+Here are the key principles that have guided the development of dothttp-runner:
 
-1. doesn't spy (or) no telemtry.
-2. dev friendly .
-3. quick import/export/share .
-4. works with existing dev tools (vscode and cli).
-5. easy to quick start and understand .
-6. save and re-use mentality . 
+1. **Respect for Privacy:** We do not collect any user data or telemetry.
+2. **Developer-Friendly:** Our goal is to provide a seamless and intuitive experience for developers.
+3. **Efficient Import/Export/Share:** Easily import, export, and share your requests.
+4. **Seamless Integration:** Works harmoniously with your existing developer tools, including VS Code and the command line.
+5. **Quick Start:** Get started with minimal setup and configuration.
+6. **Save and Reuse:** A central focus on the ability to save and reuse HTTP requests.
 
-It used be a just another cli like curl but after discussing internally with postman/insomnia users, I went on to create vscode code extension. After our first vscode extension release, there were some requests like support history, variables, multiple requests in single file, extending requests. 
+Initially conceived as a command-line tool akin to curl, feedback from discussions with Postman and Insomnia users prompted the development of a VS Code extension. After our first release, we received valuable requests for features such as request history, variable support, managing multiple requests within a single file, and extending requests.
 
-With its current usage, I felt investing any more in this is is not profitable (both professionally and personally). I will keep supporting(bug fixing) this but only for next 2-3 more months. and its reason for releasing it as 1.0.0. 
+While the current usage of dothttp-runner has been encouraging, I must candidly acknowledge that dedicating further resources to its development is not currently a viable proposition, both from a professional and personal standpoint. However, I will continue to provide support in terms of bug fixes for the next 2-3 months, and this commitment is the driving force behind the decision to release version 1.0.0.
 
-Checkout [this](https://docs.dothttp.dev/docs/dothttp-runner-notebook) (this is our most promising feature) for quick recap on what dothttp runner can offer you.
+For a quick overview of what dothttp-runner can offer you, please check out [this link](https://docs.dothttp.dev/docs/dothttp-runner-notebook), which highlights one of our most promising features. Thank you for your support and enthusiasm for dothttp-runner!
diff --git a/blog/2023-10-20-dothttp-extensions-1.0.4-1.0.5-1.0.6.md b/blog/2023-10-20-dothttp-extensions-1.0.4-1.0.5-1.0.6.md
@@ -0,0 +1,24 @@
+---
+title: dothttp-runner 1.0.3, 1.0.4, 1.0.6 Release Notes
+author: Prasanth
+author_url: https://github.com/cedric05
+tags: [dothttp-runner, vscode]
+description: Updates on the latest extension releases.
+hide_table_of_contents: false
+---
+
+
+**Version 1.0.6**
+
+- Updated dotextensions-build/cli to version 0.0.42a11.
+- Enhanced error handling for unexpected stdout from the terminal.
+- Resolved renderer issues.
+- Addressed issues #148 and #147, enabling the opening and generation of files from the sister extension dotbook.
+
+**Version 1.0.5**
+
+- The extension now intelligently avoids trying to update or upgrade the CLI when it's already built into the extension.
+
+**Version 1.0.4**
+
+- Improved platform-specific support to accommodate users behind firewalls who might face challenges when downloading dotextensions-build.
diff --git a/docs/extends.md b/docs/extends.md
@@ -1,60 +1,49 @@
 ---
-title: Extends
-slug: extend
+title: Extending Requests in dothttp
+slug: request-extension
 ---
 
-The dothttp extends is used in case of user wants to inherit request auth/headers from parent request. like oops, extendee can use base auth/headers(only auth and headers) and also override (if needed)
+The "extend" feature in dothttp allows users to inherit request authentication and headers from a parent request. This feature is especially useful for creating a hierarchy of requests where one request can use the authentication and headers defined in another ("parent") request, and potentially override them if necessary.
 
-### Extendable From Base
-- Auth defined in One request, and used everywhere else
-- Headers defined in One request and used everywhere else
-- Url join (contatinates base_url and target http url)
-- Insecure (`@insecure`)
-- Clear (`@clear`)
-- Script (user always want to run default tests)
-
-### No hierarchy
-We wanted dothttp to be simple and extendable. lets say, grandparent, parent, child with below relationships
-```text
-grandparent -> parent
-parent -> child
-```
-child will not use grandparent's any features, it will use parent (better not go for this kind of hierarchy)
+### Extending from a Base Request
+The "extend" feature enables the following capabilities:
 
+- **Authentication Inheritance:** Define authentication in one request and use it across multiple requests.
+- **Header Inheritance:** Specify headers in one request and utilize them in other requests.
+- **URL Concatenation:** Join the base URL and the target HTTP URL.
+- **Insecure Requests:** Mark requests as insecure using the `@insecure` tag.
+- **Clear Requests:** Use the `@clear` tag to clear request attributes.
+<!-- - **Script Inclusion:** Easily incorporate scripts to run default tests. -->
 
-#### example 1 (basic auth)
-
+#### Example 1: Basic Authentication
 ```http
-@name(base)  # <-- base is used to identify
+@name(base)  # <-- "base" identifies the base request
 GET "https://httpbin.org/"
 basicauth("username", "password")
 header1: headervalue1
 
-@name(sub): base # sub inherets base's auth and headers
+@name(sub): base  # "sub" inherits authentication and headers from "base"
 GET "/basic-auth/username/password"
 header2: headervalue2
 ```
 
-#### example 1 (digest auth)
-
+#### Example 2: Digest Authentication
 ```http
-@name(base)  # <-- base is used to identify
+@name(base)  # <-- "base" identifies the base request
 GET "https://httpbin.org"
 digestauth("username", "password")
 header1: headervalue1
 
-@name(sub): base # sub inherets base's auth and headers
+@name(sub): base  # "sub" inherits authentication and headers from "base"
 GET "/basic-auth/username/password"
 header2: headervalue2
 ```
 
-
-#### JWT
-
+#### JWT Authorization
 ```http
-# creates a base
-# which gathers token for each request sets it as variable
-# also, sets authorization header 
+# Create a base request
+# This base request collects the token for each subsequent request and sets it as a variable
+# It also sets the "Authorization" header in subsequent requests
 @name("base")
 GET "http://localhost:3000/api"
 "Authorization" : "{{auth=}}"
@@ -64,14 +53,14 @@ GET "http://localhost:3000/api"
 client.global.set("auth", response.headers.valueOf("Authorization"));
 
 client.test("is 200", function(){
-    client.assert(response.status ===200, "status is 200")
+    client.assert(response.status === 200, "status is 200")
 })
 
 %}
 
 /*
-    using script inherit. log `login` unwraps authorazation header from token/header
-    and checks if response code is 200
+    Using script inheritance. The "Login" request unwraps the authorization header from the token/header
+    and checks if the response code is 200.
 */
 @name("Login") : "base"
 POST "/login"
@@ -81,10 +70,11 @@ json({
 })
 
 /*
-    using script inherit. log `self` sets authorization header from earlier api. will check and update authorization header according to the latest.
-    runs tests also
+    Using script inheritance. The "self" request sets the authorization header from the earlier API request.
+    It will check and update the authorization header according to the latest data and run tests.
 */
 @name("self") : "base"
 GET "/self"
+```
 
-```
+The "extend" feature in dothttp provides a powerful and flexible way to structure and manage your HTTP requests, making it easier to reuse and customize common settings across multiple requests.
diff --git a/docs/features.md b/docs/features.md
@@ -1,32 +1,55 @@
 ---
-title: features
+title: Features of Dothttp
 
-slug: features
----
+slug: dothttp-features
+
+To get started with Dothttp, please visit the [Dothttp Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=ShivaPrasanth.dothttp-code&ssr=false#qna) for installation. With this extension installed, you can explore and experience all the remarkable features that Dothttp has to offer.
+
+## Key Features
+
+### Creating Requests with Ease
+- [Request Basics](request-basics.md)
+    - Supported Payload Types:
+        - [Support for Raw Payload (via data)](request-basics.md#example-1-text-payload)
+        - [Support for JSON Payload (via json)](request-basics.md#example-2-json-payload)
+        - [Support for URL-Encoded Payload (via json in data)](request-basics.md#example-3-urlencoded)
+        - [Support for Binary File Upload (via fileinput)](request-basics.md#binary)
+        - [Support for Multipart Upload (via files)](request-basics.md#multipart)
+
+### Organizing Multiple Requests
+- [Defining Multiple Requests in a Single File](multidef.md)
+
+### Adding Comments
+- [Commenting in Dothttp](comments.md)
+
+### Variable Support
+- [Working with Variables](variables.md)
+    - [In-File Variables](variables.md#variables)
+    - [Environment Variables from an Env File](variables.md#environment)
+    - [Individual Variables](variables.md#individual)
+
+### Writing Test Scripts
+- [Testing with Dothttp](test_scripts.md)
+
+### Extending Requests
+- [Extending Requests in Dothttp](extends.md)
+
+### Utilizing Flags
+- [Understanding Flags](extra_args.md)
+
+### Authentication Methods
+- [Authentication Options](auth.md)
+
+### Unix Socket Support
+- [Working with Unix Sockets](UnixSocket.md)
+
+### Exporting Your Work
+- [Exporting in Dothttp](export.md)
+
+### Developer-Friendly Syntax
+- Dothttp uses a syntax that is developer-friendly, enabling easy collaboration and version control with Git.
+
+### Importing Requests from Postman Collections
+- Easily import requests from Postman collections, simplifying your transition to Dothttp.
 
-please visit [dothttp-code](https://marketplace.visualstudio.com/items?itemName=ShivaPrasanth.dothttp-code&ssr=false#qna) for installation.
-
-with vscode extension installed one can try and checkout everything dothttp has to offer.
-
-## Features
-- [Create requests with ease](request-basics.md)
-    - supported payload
-        - [supports raw (via data)](request-basics.md#example-1-text-payload)
-        - [supports json payload (via json)](request-basics.md#example-2-json-payload)
-        - [supports urlencoded (via json in data)](request-basics.md#example-3-urlencode)
-        - [supports binary file upload (via fileinput)](request-basics.md#binary)
-        - [supports multipart upload via (via files)](request-basics.md#multipart)
-- [Define multiple requests in single file](multidef.md)
-- [Supports comments](comments.md)
-- [Variable support](varibles.md)
-    - [In File variable](varibles.md#variables)
-    - [env file for section of variables](varibles.md#environment)
-    - [individual variables](varibles.md#environment)
-- [Test scripts](test_scripts.md)
-- [Extends](extends.md)
-- [Flags](extra_args.md)
-- [Auth](auth.md)
-- [UnixSocket](UnixSocket.md)
-- [Export](export.md)
-- dev friendly syntax (can be committed to git repo, revisions many more)
-- import requests from postman collections link
+Explore these features to make the most of Dothttp and streamline your experience with HTTP requests and APIs.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,67 +1,66 @@
 ---
-title: Getting Started
-slug: /
----
+title: Getting Started with Dothttp
+slug: start
+
+## Introduction to Dothttp
 
-## What is Dothttp?
+Dothttp is an open-source programming language designed for testing and interacting with HTTP APIs. Its primary goal is to simplify the process of creating and maintaining API tests by offering an intuitive syntax and user-friendly commands. Dothttp is versatile and can be used for writing tests for RESTful APIs and various other HTTP-based services.
 
-Dothttp is an open-source programming language for testing and interacting with HTTP APIs. It aims to simplify the process of writing and maintaining API tests by providing a simple syntax and easy-to-use commands. Dothttp can be used to write tests for RESTful APIs and other HTTP-based services.
+The language is designed to be easily readable and comprehensible. It leverages YAML syntax to specify HTTP requests and responses, making it accessible even to those not well-versed in programming languages. Furthermore, Dothttp supports variables and functions, which enable the generation of dynamic data and code reuse.
 
-The language is designed to be human-readable and easy to understand. It uses YAML syntax for specifying HTTP requests and responses, making it easy to read and write tests even for those who are not familiar with programming languages. Dothttp also supports variables and functions, which can be used to generate dynamic data and reuse code.
+Dothttp is built on top of Python and can be effortlessly installed via pip. It provides a command-line interface (CLI) for running tests, generating reports, and debugging code. The CLI can also be seamlessly integrated with Continuous Integration (CI) systems such as Jenkins, CircleCI, and Travis CI, simplifying the automation of API tests.
 
-Dothttp is built on top of Python and can be installed using pip. It comes with a command-line interface (CLI) that allows you to run tests, generate reports, and debug your code. The CLI can also be integrated with Continuous Integration (CI) systems such as Jenkins, CircleCI, and Travis CI, making it easy to automate your API tests.
+Key features of Dothttp include:
 
-Some of the key features of Dothttp include:
+- Support for HTTP methods like GET, POST, PUT, DELETE, and more.
+- Automatic handling of cookies and sessions.
+- Support for file uploads and downloads.
+- Built-in support for JSON and XML data formats.
+- Compatibility with testing APIs secured through OAuth2 and other authentication mechanisms.
+- Extensibility through plugins.
 
-Support for HTTP methods such as GET, POST, PUT, DELETE, and more
-Automatic handling of cookies and sessions
-Support for file uploads and downloads
-Built-in support for JSON and XML data formats
-Support for testing APIs secured with OAuth2 and other authentication mechanisms
-Extensibility through plugins
-Overall, Dothttp is a powerful tool for testing and interacting with HTTP APIs. Its simplicity and ease of use make it an excellent choice for developers and testers who want to streamline their API testing process.
+All in all, Dothttp is a potent tool for testing and interacting with HTTP APIs. Its simplicity and user-friendliness make it an ideal choice for developers and testers looking to streamline their API testing process.
 
-## Step 1: Install dothttp
+## Step 1: Installing Dothttp
 
-If you haven't already, install dothttp via pip:
+To get started, if you haven't already, install Dothttp via pip:
 
 ```shell
 pip install dothttp-req
 ```
 
-or via docker
+Alternatively, you can use Docker for installation:
 
 ```shell
 docker pull quay.io/cedric05/dothttp
-# docker pull dothttp/dothttp:latest
-# prefer quay.io
 docker run -it --rm -v $(cwd):/http-files dothttp/dothttp
 ```
 
-## Step 2: Create new Http file
+## Step 2: Creating a New HTTP File
 
-simple get request with dothttp
+Let's create a simple HTTP request using Dothttp. Create a new file named `first.http` and add the following content:
 
 ```http
-//first.http
 GET https://httpbin.org/get
 ? urlparamwskey1 = urlparamsvalue2
 ? urlparamwskey2 = urlparamsvalue2
 ```
 
-run it via
-
-`python -m dothttp first.http`
+You can run this request using the following command:
 
+```shell
+python -m dothttp first.http
+```
 
-## extension installation
+## Extension Installation
 
-we ask you to use http notebooks instead of httpfiles. it comes with storing responses, shows generated properies. 
+We recommend using HTTP notebooks instead of HTTP files as they come with the capability to store responses and display generated properties.
 
-Extension url: [dothttp](https://marketplace.visualstudio.com/items?itemName=ShivaPrasanth.dothttp-code) 
+- [Dothttp Extension](https://marketplace.visualstudio.com/items?itemName=ShivaPrasanth.dothttp-code)
+- [Dothttp Notebook Ace Output Support Extension](https://marketplace.visualstudio.com/items?itemName=ShivaPrasanth.dotbook)
 
-Extension Notebook Ace output support: [dotbook](https://marketplace.visualstudio.com/items?itemName=ShivaPrasanth.dotbook)
+To install these extensions, open the extensions page in your code editor, search for "dothttp," and install both extensions.
 
-To install, open extensions page, search for dothttp and dotbook install both.
+[Watch this video to learn more about using Dothttp](https://www.youtube.com/embed/I1PtzV5Oa5c)
 
-<iframe width="720" height="480" src="https://www.youtube.com/embed/I1PtzV5Oa5c" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+This guide will help you get started with Dothttp, and you'll be on your way to efficiently testing and interacting with HTTP APIs.