Skip to main content

Visual Studio Code Extension

Introduction

Visual Studio Code is an extensible and widely used general purpose text editor. RAW Labs VS Code Extension provides a way to test your code and publish it so the final result is delivered to APIs consumers.

Introduction

tip

The extension will guide you through the bellow process.

In order to test your code you have to:

  1. Login to RAW from your VS Code.
  2. Open a GitHub repository folder as root directory in VS Code
  3. This repository should exist on GitHub (not only locally)
  4. RAW Labs should be authorized to read your repository so you have to install our GitHub reader to your repository.

The Basics

Installation

In order to install the extension search raw in the VS Code marketplace and click on install.

Installation

Layout

  • Extension and testing tabs.
    • On clicking on Extension tab, RAW Labs VS Code extension is activated and displayed.
    • On clicking on Testing tab, a unit test for APIs will be activated
  • Welcoming Page. An introductory tab that contains learning recourses, starting actions, support links and the latest news.
  • Sidebar. The Sidebar contains the current state of the environment and guides the user to set it up correctly. When the environment is set it contains the basic set of functionalities.

Layout

When Logged In and Environment is set

Layout Logged In

  1. You installation name and your username are shown here. If you use multiple environments it is shown in a formant : installation-name (environment)
  2. The current repository that you are working on. It is clickable and redirects you to the github page of the repo when clicked.
  3. Open Scratchpad opens the scratchpad (a testing editor) where you can try out your queries before creating an API
  4. Manage Credentials opens RAW Labs web app when credentials can be added.
  5. Reference guide a link to this page.
  6. Welcome page opens the Get Started view.

Get Started Tab

Layout Logged In

  1. Learning section. Here you can find learning recourses such as Getting Started Guide, Development Guide and Reference Guide.
  2. Starting section. Here you can create a new API from template, Open an existing one or clone one from GitHub.
  3. Support section.
  4. News section

Authentication

In order to be able to run queries you firstly have to Login. Without logging in you won't be able to execute queries. The authentication is needed so only you can access your Data. Security is a great concern for us.

Login

Login Page

Then press Login, the below window opens in browser and a loading bar emerges in VS Code. Please cross check the two codes to be the same before confirmation. If they are, press confirm.

Then provide your credentials from RAW Labs.

Logout

Logout

Creating new API

Assuming that you have Git installed, and already logged in. In order to create an API you need to follow 3 simple steps.

Select the template

New API

Press the Create an API button and select the directory to where you would like your template to be extracted.

Publish the generated template to GitHub

At this point, if you are not authenticated to GitHub, VS Code might ask for permission to connect to GitHub.

tip

You can just press the Enter key sequentially in order to speed up the process.

Press the Create Git Repository button, then select the directory that you use.

New API

Then select the visibility of the new repository and the files that you would like to push to the repo.

When the repo is published you will see an indication in the right bottom corner.

Success

Finally authorize RAW Labs to read the repository

Click on the Authorize button and follow the Installing GitHub Reader guide. This view will refresh automatically when the reader is installed.

RAW Labs Not Authorized

Ready to use

Your API is ready, Cheers! 🥳

Layout Logged In

Editing Code

Every endpoint consists of two parts the YAML file and RQL file (RAW Query Language) code. The yaml file is the settings of your endpoint. The RQL file is the code that generates the data for the endpoint.

yaml + rql

The overall structure should also contain a raw-site.yaml which is global setting for your endpoints. So finally you repo in the file system should look like the image below.

RQL

Scratchpad

Scratchpad is a "Playground" for testing RQL code and queries without any need of yaml settings. In order to use scratchpad you still have to login and open a repository that is published to RAW Labs.

Opening

In order to open scratchpad go to RAW extension panel tab and press the below button

Layout Logged In

For more advanced VS Code users there is also a command by pressing ctl + shift + p and type open scratchpad.

Open Scratchpad With Command

Running Code

In order to run the code there are 3 ways.

  1. Right click -> RAW - Run Scratchpad Code
  2. F8 when focused on the scratchpad

Right Click Run Click

  1. By pressing the Play button when focused on the scratchpad

Play Button

The result of your query will be visualized in a new tab.

RQL validation

RQL validation happens after running the related yaml file or scratchpad code. The errors will be visualized in the problem section as well as underlined inside the file.

Errors

Invoking RQL Autocompletion

While editing RQL files press trigger suggestion (ctrl + space default on windows and linux, To find out the keybinding on your computer go to File -> Preferences -> Keyboard Shortcuts -> Trigger Suggest" keybinding), a list will emerge with the available options.

RQL Autocomplete

Describe The Data

You can visualize the data format from data sources by ctrl + left click (or by running the Describe("location")) function in Scratchpad

Describe

Documentation on hover

When hovering RQL specific functions and keywords, their documentation is shown.

RQL Autocomplete

Commenting code

By selecting code and pressing ctrl + / the comment - uncomment is triggered.

YAML

Invoking YAML Autocompletion

While editing YAML files press trigger suggestion (ctrl + space default on windows and linux, To find out the keybinding on your computer go to File -> Preferences -> Keyboard Shortcuts -> Trigger Suggest" keybinding), a list will emerge with the available options. Every raw snippet starts with raw

YAML Snippets

Schema

Your YAML autocompletion and validation is done by importing the schema. There are two types of schemas: Site Schema and Endpoint Schema. Depending on which file you are editing, select the correspondent one. The below line of code will emerge. This enforces the restrictions on the file you are editing.

#yaml-language-server: $schema=https://cdn.raw-labs.com/raw-site-schemaV0.9.json

Pre-completion

Some of yaml fields are optional and some are required. You can pre-generate them by selecting one of the below in autocompletion:

  • raw-init-endpoint-req for only required fields
  • raw-init-endpoint-all for all the fields
  • raw-init-site-yaml for all the fields

Testing the Endpoints

RAW Labs VS Code extension supports unit testing for APIs.

Define Your Tests

In an endpoint yaml file you can define your tests.

/path/to/my-endpoint.yaml example

...
The Rest Of The Yaml File
...

tests: # <------ TESTS ARE DEFINED HERE
- name: ATest without arguments # Required
description: a simple test without arguments
- name: ATest with arguments # Required
description: a simple test with arguments
arguments:
- key: arg1
value: value_of_arg

There are two categories of tests: tests without arguments (the first test above) and tests with arguments (the second test above).

Tests without arguments

This test are for endpoints that don't take query parameters. e.g https://your-installation/endpoint

Tests with arguments

This test are for endpoints that take query parameters. e.g https://your-installation/endpoint?arg1=value_of_arg

Running tests

There are several ways of running the defined tests.

Running tests form inside the file

When the tests are defined play buttons emerge. The double play button runs all tests in the file. The single runs the specific test.

Running tests from inside the file

Testing Tab

When focusing on the testing tab, all the existing tests defined inside the workspace are shown per file (regardless the nesting of directories). You can either run all of them by pressing the "double play" button on top, or run them one by one.

Every test has a state:

  • Grey - the test hasn't run yet
  • Orange - the test is in queue
  • Green - the test passed
  • Red - the test failed because of an error

Showing endpoint output

By clicking the below icon, you can see the Data result of the test.

Running tests from inside the file

Reading the test failures

A test can fail with two types of errors:

  • Runtime Error
  • Execution Error

Runtime errors can be visualized by opening the correspondent error:

Runtime Error

Execution errors can be visualized by opening the correspondent error. There is a link inside pointing to the brocken code file :

Runtime Error

Publishing Endpoints

When you are finished creating your API. Just commit and push your repository. They will be published - updated automatically.

Environment States

RAW Labs VS Code extension interacts dynamically with the users environment. At each point it is aware of the environment state and suggests next steps to the user.

Git Not Installed

If you don't have Git installed on your machine, you will see the below state. In this case you will have to Install Git. And press the Reload button when the installation is finished.

Git Not Installed

Email or Username are not defined in Git

In order to use Git you firstly have to define you username and email (If you don't, Git will complain and suggest you do the next steps described here). The reason for that is that the Git technology can also be local only so if you do a commit, it has to attach a name to it. To do that please run the two below commands in your terminal. Press the Refresh this view button when you finish.

  • git config --global user.name "your-user-name"
  • git config --global user.email "your-user-email"

Email or Username are not defined in Git

tip

The above two steps need to be done only once. When they are done, you always will start from the next states.

User not authenticated

In order to use the RAW Labs VS Code extension, you have to login first. If you haven't registered yet, press the Register now! button to create an account. To login please follow the steps of Login section.

Login Page

No raw-site.yaml in the workspace

Every RAW Labs GitHub repository has to include a raw-site.yaml file. Without it, a repository is considered not valid. Here you can either manually create a raw-site.yaml file in the root directory, or use a Template.

No raw-site.yaml

No Git repo in the workspace

In order to use RAW Labs VS Code extension, you have to open a workspace that contains a GitHub repository. If the opened folder doesn't contain one you will see the below screen. It suggest you to initialize a local GitHub repository and directly publishing it.

No git repo

Git Origin is not set

If your workspace (root) folder contains a git repository but its origin (remote) is not set you will see the below screen. You have two options here: either to publish the repo to GitHub and set the origin to newly created (remote) repo. Or if the repo already exists on GitHub just select it as origin of your local repo.

No git origin

Wrong Git Origin is set

If your current workspace contains a repository that is not a GitHub repository, probably you opened it by mistake so the extension suggests for you to open a correct workspace. In a rare case where you have your RAW Labs repository on some other Git provider (other than GitHub), the extension suggests to either to remove the wrong origin, or to override it.

Wrong git origin

RAW Labs in not authorized to read your GitHub Repository

RAW Labs Platform needs to be authorized in order to have access to your repository. Please follow the Installing GitHub Reader guide.

RAW Labs Not Authorized

Environment is Ready

If your repository is ready to use, you will see the below screen. Cheers! 🥳

Environment Ready

Extension Settings

Please ignore this topic if you don't use multiple environments

Environment Setting

The default set environment is production, if you want to run the code against other environment, please change it in File -> Preferences -> Settings by searching RAW setting.

Environment Settings