Skip to main content

Building an API Workspace

If you are looking to generate SDKs, Developer Experience Portals or simply transforming your API definition's format to another specification format, you need to ensure that your API definition is valid for and compatible with APIMatic. This is ensured through a "Build" step that essentially converts the API definition into an intermediate format supported by APIMatic and runs additional checks on it. If the build is successful, you can proceed to generating SDKs/portals or transforming as required. If not, you will need to take some extra steps in your API definition to ensure they are ready for APIMatic. The build process for transformation is more flexible than one performed for code generation which strictly enforces a few extra checks e.g. those related to naming conventions.

Pre-Requisites​

In order to build your API workspace in the VS Code extension, it is required that your workspace has passed through the validation layer and that did not result in any validation errors (blocking or otherwise). If it did, you may see an error like below:

Build Error

Note, that validation warnings or any linting errors are allowed and will not prevent the build from proceeding.

Building the API Workspace​

To build your API workspace, you need to click the tools (🛠️) icon from the left side of the status bar:

Build Workspace

The build process will start in the background after verifying that the validation process has occurred and did not result in any blocking errors. While the build is running, you should see a Building... message in the status bar:

Build Running

Depending on whether the build passes or not, you will see a Build Passed or a Build Failed message in the status bar:

Build Success

The validation views will be populated with additional messages from the build process with codes beginning with APIMATIC. If the build fails, the messages will include errors as well.

Build Messages

You will need to re-trigger the build process each time the validation information changes for the API workspace.

Building for API Specification Transformation​

By default, the build process will enforce code generation specific checks as well. If you only intend to perform a simple API specification transformation for your API definition, you should configure the validation process as described here and set the SkipCodeGenerationChecks flag to true.