Releasing 2.0.3

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change Log
 
+## [2.0.3]
+- Made status bar less confusing when the active document is not a bundle
+- Added lots more instructions to README.md - not comprehensive but enough for most users
+
 ## [2.0.2]
 - Renamed commands from extenstion.* to zzapi.* (namespace)
 - Fixed bug: show cURL to honour file contents as body 

README.md

@@ -1,6 +1,6 @@
 # zzAPI Visual Studio Code Extension
 
-zzAPI (prounounced like pizza, the syllables interchanged) is an HTTP (REST) API documentation and testing tool, a very simplified version of Postman. [See zzAPI core](https://github.com/agrostar/zzapi/) to learn about the zzAPI file formats (`.zzb` and `.zzv` files) and philosophy.
+zzAPI (prounounced like pizza, the syllables interchanged) is an HTTP (REST) API documentation and testing tool, a very simplified version of Postman. It uses [zzAPI core](https://github.com/agrostar/zzapi/) as the underlying engine.
 
 This extension makes it easy to create, document and test API requests from within the IDE. Request bundles are YAML files with the `.zzb` extension.
 
@@ -13,28 +13,31 @@ This extension makes it easy to create, document and test API requests from with
 
 ![screencast](https://raw.githubusercontent.com/agrostar/zzapi-vscode/main/images/screencast.gif)
 
-* Provides Code Lenses above requests when a `.zzb` file is opened. These are mini-buttons that execute a request or all requests in a bundle.
-* Provides the ability to choose environments (sets of variables) to use when running requests.
-* In conjunction with [RedHat YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) provides schema validation for the `.zzb` file extension.
-* Request responses are shown in an editor window. Other response elements such as status, headers and test results are shown in the ouptput window.
-* Tests can be run against the responses. The test specification is simple and needs no coding.
+* Open-source and free forever. We will never monetize zzAPI.
+* Write HTTP Request specifications in simple YAML documents called _bundles_. The [RedHat YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) provides schema validation.
+* Storage is local (not on the cloud). You can share the specifications with your team by committing into your code repository or adding it to a shared drive.
+* Code Lenses appear above requests when a `.zzb` file (essentially a YAML with a schema) is opened. Click these to run the request. Responses are shown in a new editor window, you can save these as sample responses.
+* Define variables and group them into environments and switch between environments while running requests. Variables can be shared among bundles using separate `.zzv` files (global), or they can be local to the bundle in the `variables` section. Thus, you can share variables also with your team.
+* If you have passwords and secrets, create a separate `.zzv` file and do not commit it to the repository.
+* Run all requests in a bundle in one shot, capture variables from a response and use them in subsequnt requests (eg, get the auth token from a login and use it in subsequent requests).
+* Write tests in simple yet powerful [JSON Path](https://www.npmjs.com/package/jsonpath) specification against the response (needs no coding).
+* Document your APIs using special `doc-` nodes, or just use simple YAML comments using `# comment` syntax.
 
 ## Getting Started
 
 1. Install the [RedHat YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) extension. This is not strictly needed, but the formatting and schema validation is really helpful and useful.
-1. Install this extension
 2. Start creating a request bundle. Here is a very simple example:
 
 ```
-    requests:
-      simple-get:
-        method: GET
-        url: https://postman-echo.com/get
-        params:
-          foo1: bar1
+requests:
+  simple-get:
+    method: GET
+    url: https://postman-echo.com/get
+    params:
+      foo1: bar1
 ```
 
-4. Save the The file with a `.zzb` file extension to activate the extension.
+3. Save the The file with a `.zzb` file extension to activate the extension.
 4. Alternatively import a Postman collection:
    * Export the Postman collection as a JSON (v2.0.1) schema
    * Use the command pallete in VS Code (Cmd-Shift-P or Ctrl-Shift-P) and choose `zzAPI: Import Postman collection`
@@ -43,6 +46,160 @@ This extension makes it easy to create, document and test API requests from with
    * If you have used variables in Postman, you can also import the environments in a similar manner: export them in Postman and import them in VS Code.
 5. You will see a CodeLens above each named request for running the request. You will also see a CodeLens above the `requests` node, to run all the requests sequentially. Click on these to execute them and see the response.
 
+## A POST request with headers
+```
+requests:
+  simple-post:
+    method: GET
+    url: https://postman-echo.com/post
+    headers:
+      Content-type: application/json
+      Authorization: Basic Xfj34$fe
+    body:
+      foo1: bar1
+      foo2: [ bar2, bar3 ]
+```
+
+* Note that the body is specified in YAML but converted to JSON in the request.
+* You don't need quotes around strings and field names. YAML automatically figures out strings, numbers and booleans.
+* The content type is really not needed, and will be added automatically since the request body is a JSON
+
+## Testing response values
+```
+requests:
+  get-with-params:
+    method: GET
+    url: https://postman-echo.com/get
+    params: { foo1: bar1, foo2: bar2 }
+    tests:
+      status: 200
+      $.args.foo1: bar1
+      $.args.foo2: bar2
+```
+
+* Tests starting with `$.` are [JSON Path](https://www.npmjs.com/package/jsonpath) specs into the response body, if it is JSON, and the RHS is the expected value.
+* The HTTP status (`status`), the entire body as a string (`body`) and headers (spec starts with `$h.`) can also be tested.
+* Operators like `$.value: {$gt: 43}` are also supported (similar to MongoDB filter syntax).
+* Test results are shown in the output window (consise if all tests pass, detailed if any test fails).
+
+## Variables
+
+### Define
+
+Within the bundle:
+```
+variables:
+  staging:
+    server: https://staging.example.com
+    expectedUserId: 12345
+  production:
+    expectedUserId: 45678
+    server: https://www.example.com
+```
+
+In a separate `.zzv` file (shared across multiple bundles in the directory):
+```
+staging:
+  user: staging-user
+  password: staging-password
+production:
+  user: user
+  password: password
+```
+
+* Define variables under environments (an environment selector will appear in the status bar)
+* Use variables within the bundle when the variable is specific to this bundle
+* Use separate `.zzv` file(s) for variables that are common across bundles
+* Use separate a `.zzv` file to store secrets and passwords, do not commit to the repository
+* Define object variables (eg, `addressVar: { street: "36, Chowringee lane", city: Kolkata }`)
+
+### Set from response fields
+```
+requests:
+  get-with-params:
+    method: GET
+    url: https://example.com/login
+    params: { userId: bar1, password: bar2 }
+    setvars:
+      userName: $.data.name
+```
+
+* Specification of variable setting is similar to tests
+* Reference response body fields using JSON Path
+* Reference status, entire body (`body`) and headers (`$h.content-type`) also
+* These captured variables are available in subsequent requests, both when running requests individually as well as when running all requests
+
+### Usage
+```
+requests:
+  login:
+    url: $server/login
+    method: GET
+    params: { user: $user, password: $password }
+  tests:
+    status: 200
+    $.userDetails.userId: $expectedUserId
+```
+
+* Use variables anywhere in the request using `$variable` syntax
+* Use variables as assertion values within tests
+* Embed variables within strings like `abc$(variable)def`
+* Variables can be numbers, boolean, objects, arrays
+* Use variables in the post body like `body: { address: $addressVar }` and the variable will retain its defined type.
+
+
+## Options
+```
+requests:
+  simple-get:
+    url: $server/get
+    method: GET
+    params: { foo: foo%20bar }
+    options:
+      rawParams: true
+      follow: true
+```
+
+* By default parameters are URL encoded
+* Following redirect response is disabled by default
+* Other options are verifySSL and showHeaders (both fals by default)
+
+## Share common things across requests
+```
+common:
+  baseUrl: https://postman-echo.com
+  headers:
+    Content-type: application/json
+  tests:
+    status: 200
+  options:
+    follow: true
+
+requests:
+  Simple GET:
+    url: /get
+    method: GET
+```
+
+* Use a `common` section for all common things.
+* Use `baseUrl` for a common prefix across all requests
+* Specify headers, tests and options common to all requests
+* Each common value can be overridden in individual requests. `baseUrl` will be ignored if the request URL does not start with a `/`.
+
+## Sample responses
+```
+  simple-get:
+    url: $server/get
+    method: GET
+    params: { foo: bar }
+    response-normal: file://./responses/normal.json
+    response-failure: file://./responses/failure.json
+```
+* There is no special mechanism for response samples.
+* Just save the response as files and refer to them within the request using `response*` nodes. Use a `file://` format.
+* Use Cmd-Click or Ctrl-Click on the `file://...` links to open the sample (VS Code does this for you!)
+
+
 ## Detailed Usage
 
 The extension works with `.zzb` files, which are YAML request bundles as [described here](https://github.com/agrostar/zzapi/blob/v1.1.0/docs/zzapi-bundle-description.md).
@@ -53,12 +210,31 @@ You can best learn about the `.zzb` file format by just browsing the bundle used
 
 ## Tips and Tricks
 
-* Use OUTLINE in the VS Code Explorer sidebar to show a list of requests within the `.zzb` file: Collapse the entire tree and open only the first level of the `requests` node. Now you can easily navigate to each request for editing/running.
+* Instead of the raw body, the request body can be a YAML/JSON object. This is a great convenience compared to other API tools, where need you to create valid JSONs with quotes around every key and string. YAML is much easier to hand-create.
+
+* Non-JSON body can be specified as a string. A lengthy body with multiple lines can be written using the JSON multi-line string syntax:
 
-* Instead of the raw body, the request body can be a YAML/JSON object. This is a great convenience compared to other API tools, that need you to create valid JSONs with quotes around every key and string. YAML is much easier to hand-create.
+```
+  body: |-
+    <xml>
+      <node value="x"/>
+    </xml>
+```
 
 * Save the bundles along with your code and commit them to your repo. This is how you share them with your team. Also keep the tests right next to the code.
 
-* Multiple variable set files are merged. Keep one set as your *secrets* or *personal* set where you specify your passwords etc. needed for the requests. Do not commit this to your repo.
+* Multiple variable files are merged. Keep one set as your *secrets* or *personal* set where you specify your passwords etc. needed for the requests. Do not commit this to your repo.
+
+* Create multiple bundles within the same directory and share the variable sets among them. Or, if you prefer, declare variable sets within the bundle itself for easy visibility. Note that bundle variables override variables defined in `.zzv` files.
+
+* Create one bundle for each test case or flow. _Use Run All Requests_ to run all of them together and see their pass/fail status in the output window. Create a separate bundle with lots of comments for documenting your API set and for others to try out.
+
+* Use [JSON Path Online Evaluator](https://jsonpath.com/) to play with JSON path before using them in tests and setting variables from the response body.
+
+## Feedback, bugs and feature requests
+
+To appreaciate, give us a star in the GitHub repo: https://github.com/agrostar/zzapi-vscode
+
+For bugs, improvements and feature requests, create a new issue here:
 
-* Create multiple bundles (eg, some for documentation and some for tests) within the same directory and share the variable sets among them. Or, if you prefer, declare variable sets within the bundle itself for easy visibility.
+https://github.com/agrostar/zzapi-vscode/issues

TODO.md

@@ -1,29 +1,11 @@
 # Improvements
 
-* Support .zzb.yml in addition to .zzb. This will allow people to use yml as the extension to let VS Code dectect it as yaml even without the extension, so that it can be formatted nicely. Also, it will get formatted on github, bitbucket in the browser also. (done)
-
-* CLI Tool:
-  * Separate out core into a new repo and create a core library npm (done)
-  * zzapi-runner: command-line runner which can use the core library (done)
-
-* Rename varset as environment (done, must change schema name)
-
 * Apparently we can make a section of the document a "snippet" and associate a different language to it. Explore using "markdown" as the language for doc-* nodes.
 
 * Fix circular dependencies (Varun) (done, check on each change)
 
-* Read body from file when file:// is detected (done)
-
-* Move encoding/raw for params into options. That way we don't have to support name:xxx, value: xxx way of input (done, change tests in zzAPI)
-
-* Add Run Request and Run All Requests to command palette. (+ showCurl, done + changed to drop-down)
-
 * Multipart formdata is painful. We need some way of supporting this.
 
-* Scaffolding: using Cmd+Shift+P activate the extension and also create a directory and basic files like zz-envs.yaml and test/staging/production/local environments. (preliminary scaffolding done)
-
-* A Tree View in the explorer sidebar for selecting and executing requests (replacement for OUTLINE, which does not allow commands on the tree elements). Right now using fold All etc, but it is not that convenient. (partially done)
-
 * Cookie-jar to capture cookies automatically and add them to following requests with in the same run (or even persist?)
 
 * Path params: eg, /employees/345: URL should be /employees/:id and params can have :id set to a value

package.json

@@ -4,7 +4,7 @@
   "publisher": "AgroStar",
   "description": "Tool for testing and documenting REST APIs",
   "repository": "https://github.com/agrostar/zzapi-vscode",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "engines": {
     "vscode": "^1.70.0"
   },
@@ -352,6 +352,6 @@
     "webpack-cli": "^5.1.4"
   },
   "dependencies": {
-    "zzapi": "^1.1.0"
+    "zzapi": "^1.1.1"
   }
 }

src/EnvironmentSelection.ts

@@ -55,7 +55,7 @@ export function createEnvironmentSelector(context: ExtensionContext): void {
     // if it is not a valid bundle, we do not allow env selection
     if (!(window.activeTextEditor && documentIsBundle(window.activeTextEditor.document))) {
       window.showInformationMessage(
-        `Make a bundle (extensions: ${BUNDLE_FILE_NAME_ENDINGS}) the active editor to select a corresponding env`,
+        `Activate/open a zzAPI bundle (${BUNDLE_FILE_NAME_ENDINGS}) to select a corresponding env`,
       );
       return;
     }