REST Lens

← Back to Documentation

API Evaluation Rules

Comprehensive guide to all 40 REST API design rules evaluated by REST Lens

URI Design

Naming conventions, hierarchy, and structure

Plural Collections

Collection names should use plural nouns

URIs should not contain HTTP method names

Hierarchy Design

URIs should follow hierarchical design principles

URIs should not end with trailing slashes

No File Extensions

URIs should not include file extensions

Hyphens vs Underscores

Use hyphens, not underscores, in URIs

Lowercase Letters

URIs should use lowercase letters only

Consistent Naming Conventions

Enforce consistent naming patterns

HTTP Methods

Proper use of GET, POST, PUT, DELETE, PATCH

GET/POST Tunneling

Don't tunnel CRUD operations through GET/POST

Use GET for retrieval operations

POST for Create

Use POST for creating new resources

Create/Update Return

POST/PUT/PATCH should return the created/updated resource

Idempotent Design

POST should not be used for operations that are semantically idempotent

Toggle Anti-Pattern

POST endpoints that toggle state should be split into PUT and DELETE

Status Codes

Correct response codes for different operations

Response Error Codes

Don't use error codes in 2XX response bodies

401 Unauthorized

Operations requiring auth should define 401 response

415 Unsupported Media Type

Operations with request bodies should define 415 response

406 Not Acceptable

Content negotiation should define 406 response

412 Precondition Failed

Conditional requests should define 412 response

Location on Create

Return Location header when creating resources

Code 201 Create

Use 201 Created for successful resource creation

204 No Content must not include a response body

Content-Type Must Be Used

Responses and request bodies must specify Content-Type

Consistent Errors

Error responses should have consistent schema

Common Status Codes

Define common error codes (400, 404, 409)

HTTP Headers

Required headers for caching and concurrency

Caching Headers

GET responses should include Cache-Control header

GET responses should include Last-Modified header

GET responses for resources should include ETag

Conditional PUT

PUT operations should support conditional headers

Query Parameters

Filtering, field selection, and pagination

Query Fields GET

Support field selection via query parameters

Collection endpoints should support pagination

Query Filter Collection

Collections should support filtering parameters

Response Design

Error handling, pagination, and data formatting

XML Alternative

Consider XML alternative for JSON APIs

Consistent Media Types

API should use consistent media types across operations

Allowed Dictionary

Enforce custom domain vocabulary

Semantic Analysis

Semantic checks for naming and organization

Semantic Consistency

Detect inconsistent naming for the same concepts

Tag Organization

Operations within a tag should be semantically cohesive

Schema Field Naming

Schema field names should be intuitive

Documentation

API documentation quality

Deprecation Guidance

Deprecated endpoints should explain migration path

Every operation should have an operationId

About These Rules

Many of these rules are based on S.E.O.R.A (Static Evaluator of RESTful APIs) and other peer-reviewed REST API research. Rules are opinionated and may not fit every API design philosophy.

All rules are fully configurable: You can adjust severity levels (Error, Warning, or Info), or disable any rule entirely in your project and organization settings to match your team's standards and preferences.

Need custom rules? You can create your own rules using YAML syntax or import existing Spectral rulesets to enforce organization-specific API standards.