server-urls

Since 0.0.1 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error

This rule checks that every server URL is valid, has its scheme and host in lower case, and uses https, except on localhost.

Rule details

A server URL is copied into every client and every tool that calls the API. http on a public host sends every request, with its credentials, in clear text. Upper-case letters in a scheme or a host are the same address to DNS and to browsers, but not to a string comparison in a client, a proxy rule or a certificate check.

The rule reports Server URL is not lower case or uses http protocol on each such server.

Configuration

An object with one optional property, upgradeHttp: whether --fix changes http to https on hosts other than localhost. false by default, since the fix can only be right when the server listens on https.

Configuration example.

commands:
  lint:
    rules:
      server-urls:
        - warning
        - upgradeHttp: true

Examples

Good. https on the public host, http on localhost.

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: http://localhost:8080/v1
    description: Local development server

Bad. http on a public host, and a host in capitals.

servers:
  - url: http://api.example.com/v1
    description: Production server
  - url: https://API.EXAMPLE.COM/v1
    description: Production server with upper-case letters

Automatic fixes

--fix lowercases the scheme and the host. The user information, port, path, query, fragment and the names of server variables keep their case, since they can be case-sensitive. With upgradeHttp: true, it also changes http to https on hosts other than localhost.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.

commands:
  lint:
    rules:
      server-urls: off
Was this helpful?