Overview
When a user uploads an API specification document on APIMatic, the document is passed through certain validation steps during which a number of validation messages may be shown to the user as output. The severity of the messages will indicate whether the user can proceed to do other actions on our products with his document or not e.g. transforming the API to some other format, generating an SDK or a portal, etc. We recommend using our VS code extension for easily validating and linting your API specification documents in a more familiar environment.
Key Concepts
Rules and Rulesets
Each message shown to the user indicates a rule that was violated. Related rules are grouped together in documents called rulesets. Therefore, a rule is uniquely identified by knowing the id of the ruleset to which the rule belongs (e.g. apimatic-preliminary-validation) and the id of the rule itself (e.g. required-server-url ). If you prefer to keep things short, the same rule can also be uniquely identified with a rule code instead e.g. APIMATICPRE_V036.
Severity of Messages
The severity of the messages can range from Blocking (very severe) to Information (not severe):
| Severity Level | Details |
|---|---|
| Blocking | This is more severe than an Error. It indicates that the validation process has found a critical issue in the document that needs to be resolved before the document can be further validated. |
| Error | This is less severe than a Blocking error but is more severe than a Warning. It indicates presence of one or more syntax or semantic issues in the API specification document e.g. a request body defined in a GET method. An error will not block the validation process. However, the document needs to be fixed before it can be used to generate any further output e.g. transformed output, SDK, portal, etc. |
| Warning | This is less severe than an Error but more severe than an Information message. It indicates presence of one or more syntax/semantic issues in the API specification document which are not always severe enough to block the output generation. However, not fixing these issues in the document can affect the quality of the output e.g. a message indicating that the name exceeds maximum length restrictions can have adverse effects on the generated output. |
| Information | This is the least severe form of a message. These are generally just recommendations or suggestions that can help enhance your API definition and its completeness e.g. messages that point out that an endpoint description or a parameter example is missing. |
Rule System of a Message
The messages shown to the users can belong to two types of rule systems:
| Rule System | Details |
|---|---|
| Syntax | This system of rules is related to validity of structure of statements or expressions. It dictates which combinations of symbols, statements or expressions is valid and which is not e.g. JSON syntax dictates that all property keys are enclosed in quotes. |
| Semantic | As opposed to the syntax rule system, semantic rule system is more related to whether the constructs convey the correct meaning or are contexually valid or not e.g. a request body should not be defined in a GET method. This is syntactically valid but does not follow the semantic rule system. |
Validation versus Linting Rules
| Rule Type | Details |
|---|---|
| Validation | Validation rules check for whether your API description is valid against pre-defined standards of the format in which your API description is written. Additionally, there can be checks to ensure that your API description is technically correct or not e.g. a parameter must have a name is a validation rule. |
| Linting | Linting rules are generally style checks or recommendations that can help enhance you API description document. However, not complying with those checks will not make your document invalid. e.g. a parameter must have a description is a linting rule. |
Available Rulesets
Full list of available rulesets against which your API description file may be validated/linted is available here.
Configuring Validation and Linting
You can configure how APIMatic default validation/linting rules are applied on your API description files using the APIMatic Metadata file validation configuration feature as described here.
Adding Custom Rules
You can also create and add your own linting rules in a custom ruleset and apply that on your API description documents. For more details, please see documentation on adding your own rules.
VS Code Extension for Validation
If you use Visual Studio Code, we also offer an extension that can help you easily validate and lint multiple API description files (e.g. OpenAPI) without the need to head over to the APIMatic Dashboard each time. It will help you run standard checks on your API description files as well as additional rules enforced by APIMatic. Once validated, you can easily export your API description files to APIMatic Dashboard without leaving your extension. For more details please see detailed documentation here.