Release v2024.04

Changes:

• update [oas-tags]: add new guidelines on tags (declared, style, no more than one tag on an operation)

• new: rule [oas-comp] applies naming guidelines on all types of components (previously in [oas-types] only for schemas)

• added motivation for [oas-rdonly] why required properties shouldn’t be readOnly

• clarify that health status should be from client point-of-view in Health chapter

Release v2024.01

Changes:

• new: a document may also be a singleton that’s not part of a collection (Singleton documents)
• new: path parameter names should use lowerCamelCase [path-param]
• update: clarify that query parameters should use lowerCamelCase [uri-notat]
• update: the name of a multi-value query parameter should be singular if it’s a noun [qry-multi]
• new: explicit rule and clearer guidelines on GET /health resource [hlth-res]

Release v2023.10

Changes:

• update: [req-valid] issue type for unknown input is renamed
• new: rule [hdr-case] on case-insensitivity of HTTP headers
• update: explicit rules for guidelines: [meth-http] and [stat-codes] (use of appropriate HTTP methods and status codes), [col-sort] (sorting a collection)
• update: improved overview table for the use of HTTP methods [meth-http]
• update: corrected use of status 303: allowed on all methods in overview table [stat-codes]
• update: links to the releases of common OpenAPI definitions are added to [oas-comdef]
• update: Problem Details for HTTP APIs is updated to RFC 9457 which obsoletes RFC 7807 throughout the guide

Release v2023.06

Changes:

• add /doc/openapi.[json,yaml] to list of reserved resources
• updated [rule-id-name]: naming convention for OpenAPI types for identifiers and codes
• updated [rule-hyp-links]: avoid cross-API links, make self links optional
• updated openapi doc resources to reserved resources
• new: [rule-req-valid]: handling unknown request parameters
• updated list of OpenAPI tools

Release v2023.03

Changes:

• Rule identifier with anchor added for each rule in the guide

• Updated [jsn-naming]: naming of JSON properties

• Updated [id-name] with new naming conventions for identifiers and codes

Release v2022.12

Changes:

• new: Representing general problem types in OpenAPI

• new: Representing general and operation-specific HTTP headers in OpenAPI

Release v2022.10

Changes:

• allow (partial) response body for POST to create resource