This is the second blog in our Style Guide Rulebook Series, for the first part, go here.

REST APIs are designed around resources, which are any kind of object, data, or service that can be accessed by the client. A resource has an identifier, which is a URL that uniquely identifies that resource. Having consistent and robust URLs – will prove one of the best design decisions to build a good developer experience.

A URL consists of the following parts:

Here are some style guide rules that you can create and enforce using spectral to ensure best practices and consistency within API URLs while designing APIs.

APIs must use HTTPS protocol unless being called in a local environment i.e. localhost

Example Rule (OAS3.x)

oas3-always-use-https:
	given: $.servers[*].url
	then:
		function: pattern
		functionOptions:
			match:   http://localhost)|(https).*
	message: Servers must use the HTTPS protocol except when using localhost
	formats: oas3
	severity: error

oas2-always-use-https:
	given: $.schemes.*
	then:
		function: enummeration
		functionOptions:
	    values:
		    - https
	message: Servers must use the HTTPS protocol
	formats: oas2
	severity: warn

URLs are case sensitive but it is bad practice for them to differ based only on capitalization. This can cause a lot of confusion among developers. It is usually expected for URLs to be lowercase.

server-lowercase:
	given: $.servers[*].url
	then:
		function: pattern
		functionOptions:
			match: ^[^A-Z]*$
	message: Server URL must be lowercase
	formats: oas3
	severity: error

There are multiple conventions that organizations follow to structure their hosts. Some organizations might use *{domain}/api* while others might go for a *api.{name}.com* structure.

Popular URL conventions

Either way, whatever convention you decide on, it is important to stick to it across your API suite. For example, if you want to use `/api` convention, make sure all APIs have that in their hostnames defined in the OpenAPI.

server-has-api:
	given: $.servers[*].url
	then:
		function: pattern
		functionOptions:
	# change match to notMatch if looking to never have /api
			match: ^/api
	message: Server must have /api
	formats: oas3
	severity: error

In case you are going with another convention, it would be a good idea to never have `/api` in the path, in which case change the `Match` to `notMatch`

There can be multiple versioning strategies for APIs. Some organizations might use URL versioning while others might go for path-level versioning.

Popular versioning strategies

One common way to version is on the basepath level e.g. api.example.com/v1. If you go for this versioning strategy, make sure that all basepaths have version numbers in them.

server-version:
	given: $.servers[*].url
	then:
		function: pattern
		functionOptions:
	# use version[1-9] if looking for /version1 instead of /v1
	# change match to notMatch if looking to never have version on host level
			match: ^.*/v[1-9]
	message: Server must have end with a version
	formats: oas3
	severity: error

Moreover, it’s a good idea to just have major versions within your base path. You can enforce that with the following configuration.

server-major-version-only:
	given: $.servers[*].url
	then:
		function: pattern
		functionOptions:
			notMatch: .
	message: Server should only have major versions
	formats: oas3
	severity: error

If you are using path versioning, make sure that all paths have version numbers in them.

path-casing:
	given: $.paths
	then:
	# Targeting the key of paths object i.e. /products/{productId}
		field: @key
		function: pattern
		functionOptions:
	# For underscore_case: ^/([a-z0-9]+(_[a-z0-9]+)*)?(/[a-z0-9]+(_[a-z0-9]+)*|/{.+})*$
	# For camelCase case: ^/([a-z][a-zA-Z0-9]+)?(/[a-z][a-zA-Z0-9]+|/{[a-z][a-zA-Z0-9]+})*$
			match: ^/([a-z0-9]+(-[a-z0-9]+)*)?(/[a-z0-9]+(-[a-z0-9]+)*|/{.+})*$
	message: Paths must be kebab-case
	severity: error

Paths are usually one of the following across popular APIs: kebab-case, underscore_case, or camelCase. It is advisable to use kebab-case, as It typically looks clearer and hence more user-friendly than using underscores (_).

Popular URL casing conventions

Again irrespective of the casing you choose it’s important to stay consistent.

In general, it’s usually preferred to use plural nouns for resources unless a plural doesn’t exist for the noun.

resource-names-plural:
	given: $.paths
	then:
	# Targeting the key of paths object i.e. /products/{productId}
		field: @key
		function: pattern
		functionOptions:
			match: ^((/vd+)*((/[w+-]*s)(/{.*})*)*)$
	message: Resource names should generally be plural
	# Don’t create this as an error, but rather a warning or info level rule,
	# considering there are exceptions for singleton resources.
	severity: warn

*/users* and */users/* are considered to be separate paths but it is bad practice for them to differ based only on a trailing slash. This can cause confusion among users of your API.

It is usually preferred to not have a trailing slash.

Again, either way, be consistent by creating a rule.

paths-no-trailing-slash:
	given: $.paths
	then:
	# Targeting the key of paths object i.e. /products/{productId}
		field: @key
		function: pattern
		functionOptions:
			notMatch: /$
	message: Paths must not end with a trailing slash
	severity: error

The use of file extensions is simply seen as unnecessary in URLs. This is because it can cause some issues for the end-users if you change the file type of the results. Hence, it might add unnecessary complexity that you would like to avoid.

paths-no-trailing-slash:
	given: $.paths
	then:
	# Targeting the key of paths object i.e. /products/{productId}
		field: @key
		function: pattern
		functionOptions:
	# Feel free to add other extensions to this list
			notMatch: (JSON|json|XML|xml)
	message: Paths must not have file extensions
	severity: error

When you design a REST API, you don’t usually need to mention terms like `get`, `delete` and so on in your `paths`, because this information is conveyed by the HTTP method.

paths-no-trailing-slash:
	given: $.paths
	then:
	# Targeting the key of paths object i.e. /products/{productId}
		field: @key
		function: pattern
		functionOptions:
	# Feel free to add other verbs to this list
			notMatch: (GET|PUT|POST|DELETE|LIST|CREATE|REMOVE)
	message: Paths must not have HTTP verbs in them
	severity: error

paths-version-number:
	given: $.paths
	then:
	# Targeting the key of paths object i.e. /products/{productId}
		field: @key
		function: pattern
		functionOptions:
	# Change match to notMatch if you're not looking for versions on the path level
			match:  (/v[1-9]|/version[1-9])
	message: Paths must have a version in them
	severity: error

URLs can only be sent and received using the ASCII character set, your API URLs should contain only ASCII characters. However, that does not mean you can just use all the characters. Special characters like %20 should not be used in paths.

paths-avoid-special-characters:
	given: $.paths
	then:
	# Targeting the key of paths object i.e. /products/{productId}
		field: @key
		function: pattern
		functionOptions:
	# Change match to notMatch if you're not looking for versions on the path level
			notMatch:  ^[$&+,;=?@]*$
	message: Avoid using special characters in paths
	severity: warn

Using nouns for resource names leads to easier-to-use APIs. This can be done via custom functions in Spectral which we’ll cover in another article in this series.

Query parameters in OpenAPI are defined separately. Adding them to the path itself should be avoided.

paths-no-query-params:
	given: $.paths
	then:
	# Targeting the key of paths object i.e. /products/{productId}
		field: @key
		function: pattern
		functionOptions:
			notMatch: ?
	message: Paths should not have query parameters in them. They should be defined separately in the OpenAPI.
	severity: warn

Path parameters are usually underscore_case or camelCase.

Popular path parameter casing conventions

path-parameters-camelcase:
	given: $..parameters[?(@.in == 'path')].name
	then:
		function: casing
		functionOptions:
			type: camel
			disallowDigits: true
	message: Path parameters should be camelCase and not contain digits
	severity: error

Query parameters are usually underscore_case or camelCase.

Popular query parameter casing conventions

query-parameters-camelcase:
	given: $..parameters[?(@.in == 'query')].name
	then:
		function: casing
		functionOptions:
			type: camel
			disallowDigits: true
	message: Query parameters should be camelCase and not contain digits
	severity: error

It is usually a good idea to have both query and path parameters follow the same conventions.

Path parameters should be defined on the path level instead of the operation level.

path-parameters-camelcase:
	given: $.paths[*][*].parameters[?(@.in == 'path')]
	then:
		function: falsy
	message: Path parameters should be defined on the path level instead of the operation level.
	severity: warn

APIs MUST have a status path defined (/status), to easily get started with an API and ping for status updates.

status-path-defined:
	given: $.paths[*][*]
	then:
		function: truthy
	message: APIs MUST have a status path defined (`/status`)
	severity: warn

With not much standardization and so many conventions to worry about when building REST APIs, a core set of guidelines that everybody agrees on is necessary. Convert them into style guide rules that can then be enforced as part of the design and governance process. A combination of these rules helps you create consistent REST API URLs, which leads to an enhanced developer experience. After all, over 50% of organizations use or plan on using internal style guidelines this year, and standardization is the #1 challenge teams are looking to overcome this year, according to the State of API report (2022). This is simply another way you can implement consistency and standardization in your own API program!

Get started with these rules in this sample project.

For more information on style guides, check out our feature blog or our open-source linting tool, Spectral. If you have other ideas on URL conventions and rules, submit an idea on our product roadmap.