Setting Up an API Workspace
To work with one or more API definitions in the APIMatic's VS Code extension, you are first required to set up a dedicated API workspace with all relevant files. There are several ways available to set up your workspace and we will walk you through each of the available options below.
Ensure that your API workspace contains only relevant files for the API definition. See tips for working with large workspaces in the extension without affecting performance.
Opening an API Workspace
Navigate to the APIMatic API Explorer view from the Activity bar. Based on your usage, you may see one or more of the following options:
Here is what you can expect from each of these:
Option 1: Open a New API Workspace
If you are a new extension user with no open folder, you will see this option labelled as Open Workspace Folder. For older users returning to the extension, this option will be marked as Open New Workspace Folder. As the name suggests, this option will let you browse your system for a folder that you can use as your API workspace.
Choose a folder and click on Select Folder to open it in the APIMatic API Explorer view. Note, that this will close your existing workspace session, if any.
Option 2: Open Last API Workspace
This option will be labelled as Open Last API Workspace Session in the list and will only be visible if you've previously worked on an API workspace. Selecting this option will help restore your last API workspace session so you can resume working from where you left.
Option 3: Use Current Workspace as API Workspace
This option will be labelled as Use Current Workspace Folder in the list and will only be visible if you have a workspace folder open that is not already marked as an API workspace. Selecting this option will keep your current folder open but will make it accessible in the APIMatic API Explorer view as well.
Adding an API Definition to Your Workspace
Once you have your API workspace ready, you can begin the next steps of adding an API definition along with any relevant files. We offer some options to help you get started, in the Open/Create API Definition side view which are discussed in more detail in the next few sections.
Adding/Importing an Existing API Definition
If you already have a raw API definition file in your local system somewhere or at a public URL, you can import that into your workspace using relevant import options. You can even add a sample file instead if you are just looking to explore the extension and get an idea of things. All of these options should be visible to you under the Add/Import title.
Option 1: Adding a Sample File
Click on Add Sample File. You will be asked to select the desired output format (json or yaml) after which a sample-petstore.<ext> will be added in your API workspace instantly.
Option 2: Importing an Existing File from Local System
You can browse your local system and import any existing API definition file into your current API workspace using the Import Existing File option. The API definition file must be in one of the supported formats. Note, that multi-file selection or ZIP files are not supported for this option.
Option 3: Importing an Existing File from Public URL
If your raw API definition file is available publicly at a URL, you can import it into your current API workspace using the Import File from Public URL option. The API definition file must be in one of the supported formats. Note, that multi-file selection or ZIP files are not supported for this option.
Ensure that you have a stable network connection and then provide a valid public URL path in the input dialog that opens:
If the URL is valid, the file should download successfully into your workspace in a few seconds (depending upon the size):
Creating an API Definition from Scratch
If you do not have an API definition, you can create one from scratch using options listed under the Create title.
Option 1: From an Empty File
Click on Create Empty File. You will be asked to select the desired output format (json or yaml) after which a openapi.<ext> will be added in your API workspace instantly.
We recommend defining your API using the latest available OpenAPI version. You can view reference documentation for the OpenAPI specification within the extension by clicking on the OpenAPI format name in the status bar at the bottom right side.
Option 2: From a Template
We can help you create a basic OpenAPI definition by collecting relevant metadata and generating an API definition accordingly. Click on the Create File from Template option to begin.
First, you will be required to enter a short meaningful name for your API service:
Next, you will be asked to briefly describe what service your API provides:
Next, enter the URL of the server at which your API is served:
Lastly, pick an output format for your API definition file (JSON/YAML):
After the above data is collected, an API definition file will be instantly generated in your API workspace based on the collected information:
Closing an API Workspace
To close a currently open API workspace, you can use the Close API Workspace option from the Manage Session view:
You will be asked to confirm this action before proceeding:
Once closed, validation and other features will not work until the workspace is opened as an API workspace again.
Closing the API workspace will only close it in the extension. The workspace will still remain open in VS Code.
Managing Large Workspaces
For optimal performance, it is recommended to keep the API workspace small and focused with only relevant files present. Ideally, the workspace should not exceed 20MB in size. However, if you have a large workspace that you would like to open in your VS code, there are certain ways available to improve extension performance. Without those measures, you may encounter performance related warnings as shown below:
Here are some tips for better performance when working with large workspaces:
Manually delete any extra files or folders that are not relevant and can be safely removed.
Exclude the files or folders that are not directly related to the API definition itself using the Workspace File Navigator view's Exclude option:
Excluded files/folders will remain in the workspace but will be safely ignored by the extension for all of its operations.