RESTful

aid: restful
name: RESTful
description: 'Representational State Transfer (REST) is an architectural style for designing networked applications using
  stateless HTTP communication and uniform interfaces. RESTful describes systems and APIs that conform to the REST constraints:
  client-server separation, statelessness, cacheability, layered system, uniform interface, and (optionally) code-on-demand.
  This index covers the RESTful design paradigm including maturity models, API design patterns, documentation formats, and
  key reference implementations.'
type: Index
url: https://raw.githubusercontent.com/api-evangelist/restful/refs/heads/main/apis.yml
tags:
- Architecture
- HTTP
- Web Services
created: '2025-01-01'
modified: '2026-05-02'
specificationVersion: '0.19'
apis:
- aid: restful:richardson-maturity-model
  name: Richardson Maturity Model
  description: 'A model by Leonard Richardson that breaks down the maturity of a RESTful API into four levels: Level 0 (The
    Swamp of POX), Level 1 (Resources), Level 2 (HTTP Verbs), and Level 3 (Hypermedia Controls / HATEOAS). Most modern APIs
    target Level 2.'
  humanURL: https://martinfowler.com/articles/richardsonMaturityModel.html
  tags:
  - Best Practices
  - Design Patterns
  - Maturity Model
  properties:
  - type: Documentation
    url: https://martinfowler.com/articles/richardsonMaturityModel.html
- aid: restful:json-api
  name: JSON:API
  description: A specification for building APIs in JSON that standardizes resource representation, relationships, error handling,
    and metadata. Reduces over-fetching and under-fetching with sparse fieldsets and compound documents.
  humanURL: https://jsonapi.org/
  tags:
  - Hypermedia
  - JSON
  - Standards
  properties:
  - type: Documentation
    url: https://jsonapi.org/format/
  - type: Website
    url: https://jsonapi.org/
- aid: restful:hal-specification
  name: HAL - Hypertext Application Language
  description: A simple format for including hypermedia links in JSON or XML API responses. HAL uses _links for links and
    _embedded for embedded resources, providing a consistent way to make REST APIs navigable.
  humanURL: https://stateless.co/hal_specification.html
  tags:
  - Hypermedia
  - JSON
  - Standards
  properties:
  - type: Documentation
    url: https://stateless.co/hal_specification.html
  - type: IETF Draft
    url: https://datatracker.ietf.org/doc/html/draft-kelly-json-hal
- aid: restful:openapi-specification
  name: OpenAPI Specification
  description: The OpenAPI Specification (OAS) defines a standard, language-agnostic interface for HTTP APIs. OpenAPI 3.x
    is the most widely-used format for describing RESTful APIs, enabling documentation, code generation, and validation.
  humanURL: https://spec.openapis.org/oas/latest.html
  tags:
  - Documentation
  - Standards
  - Tooling
  properties:
  - type: Specification
    url: https://spec.openapis.org/oas/latest.html
  - type: Website
    url: https://www.openapis.org/
- aid: restful:http-rfc-9110
  name: RFC 9110 - HTTP Semantics
  description: 'The IETF standard defining HTTP semantics: methods, status codes, header fields, content negotiation, authentication,
    and request/response message formats. The authoritative reference for RESTful HTTP API design.'
  humanURL: https://datatracker.ietf.org/doc/html/rfc9110
  tags:
  - HTTP
  - RFC
  - Standards
  properties:
  - type: Standards
    url: https://datatracker.ietf.org/doc/html/rfc9110
common:
- type: DomainSecurity
  url: security/restful-domain-security.yml
- type: Roy Fielding REST Dissertation
  url: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
- type: IANA HTTP Status Codes
  url: https://www.iana.org/assignments/http-status-codes/
- type: IANA Link Relations
  url: https://www.iana.org/assignments/link-relations/
- type: RFC 6570 URI Templates
  url: https://datatracker.ietf.org/doc/html/rfc6570
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com