Define & Validate APIsValidation RulesetsAPIMatic Rulesets
APIMatic Preliminary Linting
APIMatic performs some preliminary linting checks on the user-provided API specification to ensure that the API specification document produces desired output in any of the APIMatic products including API Transformer, SDK/Portal generation, etc.
| Property | Value |
|---|---|
| Ruleset ID | apimatic-preliminary-linting |
| Code prefix | APIMATICPRE_L |
| Type | Linting |
| Default severity | Warning |
| Rule system | Semantic |
| Rules | 24 |
API
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_L001 | valid-api-version | Warning | The API version must be non-null, non-empty and follow semantic versioning rules. |
APIMATICPRE_L002 | valid-contact-url-format | Warning | String value should be in the format of a proper URL. |
Server Configuration
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_L011 | atleast-one-server-template-parameter-reference | Warning | Template parameters defined in the server configuration must be referenced by at least one or more server URLs. |
Authentication
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_L021 | no-oauth-2-parameter-paramformats | Warning | The OAuth 2.0 parameter has no record for allowed formats indicating how it must be sent, therefore, the currently specified formats will not be taken into consideration. |
APIMATICPRE_L022 | api-authentication-mechanism-defined | Information | APIs almost always require only authorized users to make requests to the API server. For this, a particular authentication mechanism is required to be followed. If the API requires authentication, the authentication mechanism must be defined globally in the authentication section of the relevant API description format. Endpoints not requiring any authentication can be excluded as required. |
APIMATICPRE_L023 | unique-authentication-options | Warning | An authentication option in a list of options must be unique. The uniqueness of an authentication option is determined by uniqueness of the authentication schemes that need to be applied as part of this option, required scope values, etc. |
APIMATICPRE_L024 | unique-authentication-schemes-in-group-auth-option | Warning | A group authentication option is one that makes use of multiple authentication schemes to complete the authentication. It must not consist of any duplicate authentication schemes. |
APIMATICPRE_L025 | two-or-more-authentication-schemes-in-group-auth-option | Warning | A group authentication option is expected to make use of multiple authentication schemes to complete the authentication. Therefore, it must consist of at least two or more authentication schemes. If only a single authentication scheme is present, it is recommended to change the authentication option type to single. |
Endpoints
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_L041 | endpoint-group-globally-defined | Warning | An endpoint can only be placed inside an endpoint group which is pre-defined under the API level endpoint groups definition. |
APIMATICPRE_L042 | optional-template-path-parameters | Warning | Path/template parameters used in the endpoint relative path/route should not be defined as optional parameters in the endpoint. |
APIMATICPRE_L043 | atleast-one-template-parameter-reference | Warning | If a template parameter is defined in an endpoint, it must also be part of one or more path segments of the endpoint's relative path/route. |
APIMATICPRE_L044 | no-endpoint-authorization-header | Information | A declaration of Authorization header at endpoint level is not recommended. Alternatively, make use of the appropriate authentication scheme for the API which will automatically enable the authentication globally for all your endpoints except those that do not require authentication. |
APIMATICPRE_L045 | concrete-response-type | Information | If your response type is set to Void or Dynamic, it may be because enough information about response type could not be deduced from your API description response information. Make sure that Void is set for only those responses where no response body is expected. And Dynamic is used where the response type information cannot be easily represented or you need to allow multiple types. In all other cases, a valid primitive or model type must be used for the response. |
Types/Models
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_L101 | no-base-type-field-redeclaration | Warning | Fields/properties must not be re-declared in a model if they have already been defined in the model's base type or type hierarchy. |
APIMATICPRE_L102 | no-model-circular-dependency | Warning | A model containing one or more required fields (whether inherited or not) which reference the same model either directly or indirectly indicates presence of a circular dependency. Referencing a model (say A) indirectly means the field(s) references another model (say B) which may contain one or more fields that directly or indirectly reference the model under consideration (A). |
APIMATICPRE_L103 | valid-number-type-restriction-attribute | Warning | The value of a numeric type restriction attribute must be an integer greater than, or equal to zero. |
APIMATICPRE_L104 | maximum-limit-greater-or-equal-minimum-limit | Warning | The value of maximum limit set by a numeric type restriction attribute cannot be less than the specified minimum limit. In other words, the minimum value set by a numeric type restriction attribute cannot exceed the specified maximum limit |
APIMATICPRE_L105 | no-inline-model-definition | Warning | It is recommended that a model definition is added globally with a unique name and then referenced throughout the API description with that name. Inline definitions of models with components are not recommended as the names of such models are generated from the components in which they are declared. This can result in duplicate names which are handled by appending a number at the end. This behavior can affect your output quality. |
APIMATICPRE_L106 | no-redundant-model | Information | To get a good quality output, it is recommended to avoid redundant models. A redundant model can be one which has exactly the same properties as another model or which is a subset of another model so that it can be easily replaced by its superset model instead. |
APIMATICPRE_L107 | atleast-one-or-more-model | Information | Complex data like JSON objects, arrays or enumerations must be defined using the global models/custom types in the API description file and then referenced in the request parameters or responses as required. This gives you better control over your API data as you can then easily serialize and deserialize the data when making API calls via our products like SDKs, etc. |
APIMATICPRE_L108 | non-zero-multiple-of-restriction-attribute | Warning | The value of the 'multipleOf' numeric type restriction attribute must be a number strictly greater than zero. |
APIMATICPRE_L195 | non-empty-type-combinator-metadata | Warning | When a metadata is specified for each of the type combinator cases, it is expected to add more information to the cases like assigning a user-friendly name to the case, adding additional descriptive content, etc. If, however, the metadata provides none of these details, it is considered redundant. |
APIMATICPRE_L196 | atleast-one-type-combinator-set-in-global-type-combinators | Warning | A global type combinators definition expects at least one type combinator definition e.g. anyOf, oneOf, not. This means that the type cases in a type combinator must contain at least one type case. |
Miscellaneous
| Code | Rule | Severity | What it checks |
|---|---|---|---|
APIMATICPRE_L201 | supported-vendor-extensions | Information | APIMatic supports certain vendor extensions which are loaded at the time of importing API description files containing these extensions. These include APIMatic specific extensions as well that are used for configuring products like Code Generation, Transformer, etc. All other extensions will be ignored or may not work as expected. |
APIMatic Post-Processing Validation For Code Generation
APIMatic post-processes a user-provided API specification document and automatically fixes some common issues that can impact code generation. This validation helps inform users about these issues and the fixes performed.
APIMatic Linting for Portal Generation
APIMatic performs some preliminary linting checks on the user-provided API specification file to ensure that the docs/portal generation produces the desired output.