API Style Guides

A landscape index of public API style guides published by leading technology companies and standards bodies. API style guides codify conventions for resource modeling, URI design, HTTP method use, status codes, error formats, pagination, versioning, deprecation, idempotency, hypermedia, and security so that APIs across an organization (or an industry) behave consistently. This topic repo catalogs the canonical industry style guides, compares the pillars each one chooses to mandate, and provides a shared vocabulary and JSON Schema for describing individual style guide rules.

API Style Guides publishes 11 APIs on the APIs.io network. Tagged areas include API Style Guides, API Design, API Governance, REST, and OpenAPI.

The API Style Guides catalog on APIs.io includes 1 JSON-LD context and 1 Spectral governance ruleset.

API Style Guides’ developer surface includes code examples and 10 more developer resources.

🌐 Visit website 📡 Source on GitHub

24.9/100 emerging ▼ -6.0 Agent 2/100 human only Full breakdown ↓
scored 2026-07-28 · rubric v0.6

11 APIs

API Style GuidesAPI DesignAPI GovernanceRESTOpenAPIConventionsStandardsDocumentation

Kin Score

Kin Score How this is scored →
scored 2026-07-28 · rubric v0.6

Composite quality — 24.9/100 · emerging

Contract Quality 6.9 / 25

Developer Ergonomics 1.7 / 20

Commercial Clarity 0.0 / 20

Operational Transparency 0.7 / 13

Governance 8.3 / 12

Discoverability 7.4 / 10

Agent readiness — 2/100 · human only

Machine-Readable Contract 0 / 18

Agentic Access Contract 0 / 10

MCP Server 0 / 12

Machine-Readable Auth 0 / 10

Idempotency 0 / 9

Stable Error Semantics 0 / 8

Request/Response Examples 7 / 7

Rate-Limit Signaling 0 / 7

Typed Event Surface 0 / 6

Agent Skills 0 / 5

Well-Known Catalog 0 / 4

Consent & Bot Identity 0 / 3

A2A Agent Card 0 / 8

Dry-Run / Simulate Mode 0 / 4

Improve this rating by publishing the missing artifacts — every area above can be raised, and the full rubric is at apis.io/rating/. This rating is computed from github.com/api-evangelist/style-guides: open an issue to ask a question, or submit a pull request to add artifacts. Want it done for you? Prioritized profiling — $2,500 →

APIs 11

Individual APIs this provider publishes, each with its own machine-readable definition.

GraphQL 1

GraphQL schemas published by this provider.

JSON Schema 1

Standalone JSON Schema definitions for this provider's data models.

API Style Guide Rule

15 properties

JSON SCHEMA

Examples 18

Example request and response payloads for these APIs.

Scroll for all 18

Get Started 1

Portal, sign-up, and the first successful call

DeveloperPortal

DeveloperPortal

Documentation 1

Reference material describing how the API behaves

JSONSchema

JSONSchema

Design & Contract 2

Pagination, idempotency, versioning, errors, and events

JSONLD

JSONLD

Vocabulary

Vocabulary

Build 2

SDKs, sample code, and the tooling you integrate with

Examples

Examples

GitHubOrganization

GitHubOrganization

Access & Security 1

Authentication, authorization, and security posture

DomainSecurity

DomainSecurity

Other 4

Properties that don't map to a standard resource type

Network

RelatedTopic

RelatedTopic

RelatedTopic

Source (apis.yml)

aid: style-guides
name: API Style Guides
description: A landscape index of public API style guides published by leading technology companies and standards bodies.
  API style guides codify conventions for resource modeling, URI design, HTTP method use, status codes, error formats, pagination,
  versioning, deprecation, idempotency, hypermedia, and security so that APIs across an organization (or an industry) behave
  consistently. This topic repo catalogs the canonical industry style guides, compares the pillars each one chooses to mandate,
  and provides a shared vocabulary and JSON Schema for describing individual style guide rules.
type: Index
accessModel:
  pricing: unknown
  onboarding: unknown
  trial: false
  try_now: false
  public: false
  label: Unknown
  confidence: low
  source: []
  generated: '2026-07-22'
  method: derived
image: https://kinlane-images.s3.amazonaws.com/shared/api-evangelist-logos/api-evangelist-logo-butterfly.png
tags:
- API Style Guides
- API Design
- API Governance
- REST
- OpenAPI
- Conventions
- Standards
- Documentation
url: https://raw.githubusercontent.com/api-evangelist/style-guides/main/apis.yml
created: '2026-05-22'
modified: '2026-05-22'
specificationVersion: '0.19'
apis:
- aid: style-guides:microsoft
  name: Microsoft REST API Guidelines
  description: Microsoft's organization-wide REST API design guidelines, originally published in 2016 and now maintained as
    separate Azure and Microsoft Graph guideline documents under the umbrella Guidelines.md. Licensed CC BY 4.0 to encourage
    adoption beyond Microsoft.
  humanURL: https://github.com/microsoft/api-guidelines
  baseURL: https://raw.githubusercontent.com/microsoft/api-guidelines/vNext/
  tags:
  - REST
  - Microsoft
  - Azure
  - Microsoft Graph
  - OData
  properties:
  - type: StyleGuide
    url: https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md
  - type: AzureStyleGuide
    url: https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md
  - type: GraphStyleGuide
    url: https://github.com/microsoft/api-guidelines/blob/vNext/graph/GuidelinesGraph.md
  - type: License
    url: https://github.com/microsoft/api-guidelines/blob/vNext/license.txt
  - type: GitHubRepository
    url: https://github.com/microsoft/api-guidelines
  - type: Scope
    data:
      surfaces:
      - REST
      publisher: Microsoft
      license: CC BY 4.0
      status: living
- aid: style-guides:google-aip
  name: Google API Improvement Proposals (AIPs)
  description: Google's design review system, modeled on Python PEPs and Rust RFCs. AIPs are numbered, individually reviewable
    design documents covering resource-oriented design, standard methods, errors, pagination, naming conventions, and long-running
    operations. Maintained at aip.dev with content under CC BY 4.0 and code samples under Apache-2.0.
  humanURL: https://google.aip.dev/
  baseURL: https://google.aip.dev/
  tags:
  - REST
  - gRPC
  - Resource-Oriented
  - Google
  properties:
  - type: StyleGuide
    url: https://google.aip.dev/
  - type: GitHubRepository
    url: https://github.com/aip-dev/google.aip.dev
  - type: ContentLicense
    url: https://creativecommons.org/licenses/by/4.0/
  - type: CodeLicense
    url: https://www.apache.org/licenses/LICENSE-2.0
  - type: Scope
    data:
      surfaces:
      - REST
      - gRPC
      publisher: Google
      license: CC BY 4.0 (content) / Apache-2.0 (code)
      status: living
      approxRules: 70+ (general AIPs)
- aid: style-guides:zalando
  name: Zalando RESTful API and Event Guidelines
  description: The canonical open community style guide. Maintained by Zalando's API Guild and widely cited as the reference
    implementation for an API-First, OpenAPI-based REST and event-driven API program. Roughly 150+ numbered MUST/SHOULD/MAY
    rules covering REST basics, design, operation, and AsyncAPI-style event types.
  humanURL: https://opensource.zalando.com/restful-api-guidelines/
  baseURL: https://opensource.zalando.com/restful-api-guidelines/
  tags:
  - REST
  - Events
  - API First
  - OpenAPI
  - Zalando
  properties:
  - type: StyleGuide
    url: https://opensource.zalando.com/restful-api-guidelines/
  - type: GitHubRepository
    url: https://github.com/zalando/restful-api-guidelines
  - type: SpectralRuleset
    url: https://github.com/zalando/zally
  - type: Scope
    data:
      surfaces:
      - REST
      - Events
      publisher: Zalando SE
      license: CC BY 4.0
      status: living
      approxRules: 150+
- aid: style-guides:paypal
  name: PayPal API Design Guidelines
  description: PayPal's API style guide covering service design principles, HTTP methods, hypermedia, naming, URI structure,
    JSON schema and types, error handling, versioning, and deprecation. The original repository at github.com/paypal/api-standards
    was archived; the content is preserved in community forks.
  humanURL: https://github.com/paypal/api-standards
  baseURL: https://raw.githubusercontent.com/KuSh/api-standards/master/
  tags:
  - REST
  - HATEOAS
  - PayPal
  - Payments
  properties:
  - type: StyleGuide
    url: https://github.com/paypal/api-standards
  - type: ArchiveMirror
    url: https://github.com/KuSh/api-standards
  - type: PatternsLibrary
    url: https://github.com/KuSh/api-standards/tree/master/patterns
  - type: Scope
    data:
      surfaces:
      - REST
      publisher: PayPal
      license: not explicitly stated; CC-style sharing language in repo
      status: archived (mirrored)
- aid: style-guides:adidas
  name: adidas API Guidelines
  description: adidas group's API guidelines covering general principles, REST conventions, and asynchronous (Kafka / AsyncAPI)
    event design. Ships with a Spectral ruleset that validates both OpenAPI and AsyncAPI specifications against the guideline.
    MIT licensed.
  humanURL: https://github.com/adidas/api-guidelines
  baseURL: https://raw.githubusercontent.com/adidas/api-guidelines/master/
  tags:
  - REST
  - AsyncAPI
  - Kafka
  - adidas
  - Spectral
  properties:
  - type: StyleGuide
    url: https://github.com/adidas/api-guidelines
  - type: SpectralRuleset
    url: https://github.com/adidas/api-guidelines/tree/master/spectral
  - type: GitHubRepository
    url: https://github.com/adidas/api-guidelines
  - type: Scope
    data:
      surfaces:
      - REST
      - AsyncAPI
      publisher: adidas
      license: MIT
      status: living
- aid: style-guides:cisco
  name: Cisco REST API Design Guide
  description: Guidelines for Designing REST APIs at Cisco, developed across Cisco DevNet, Collaboration, and the Application
    Platform Group. Emphasizes "API-only" communication, aesthetic and behavioral consistency, OAuth2 / HTTPS security, and
    avoidance of internal vs. partner API bifurcation.
  humanURL: https://github.com/CiscoDevNet/api-design-guide
  baseURL: https://raw.githubusercontent.com/CiscoDevNet/api-design-guide/master/
  tags:
  - REST
  - Cisco
  - DevNet
  - OAuth2
  properties:
  - type: StyleGuide
    url: https://github.com/CiscoDevNet/api-design-guide
  - type: GitHubRepository
    url: https://github.com/CiscoDevNet/api-design-guide
  - type: Scope
    data:
      surfaces:
      - REST
      publisher: Cisco Systems
      license: see repository (Cisco copyright 2015-2024)
      status: living
- aid: style-guides:atlassian
  name: Atlassian REST API Design Guidelines
  description: Atlassian's REST API design guidelines, applied across Jira, Confluence, Crowd, and plugin REST modules. Defines
    URI conventions (singular resources, versioned paths, expand/start-index/max-results query parameters), HTTP method semantics,
    response codes, and versioning policy.
  humanURL: https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-rest-api-design-guidelines-version-1/
  baseURL: https://developer.atlassian.com/
  tags:
  - REST
  - Atlassian
  - Jira
  - Confluence
  properties:
  - type: StyleGuide
    url: https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-rest-api-design-guidelines-version-1/
  - type: Scope
    data:
      surfaces:
      - REST
      publisher: Atlassian
      license: documentation under Atlassian terms
      status: v1 (legacy server framework)
- aid: style-guides:heroku
  name: Heroku Platform API Design Conventions
  description: Heroku's design conventions for the Platform API, documented in the Platform API Reference and the API Compatibility
    Policy. Notable for versioned media types (application/vnd.heroku+json; version=3), JSON Schema discovery via /schema,
    Range-based pagination, stability levels (prototype / development / production), and structured error payloads.
  humanURL: https://devcenter.heroku.com/articles/platform-api-reference
  baseURL: https://api.heroku.com
  tags:
  - REST
  - Heroku
  - JSON Schema
  - Stability Levels
  properties:
  - type: StyleGuide
    url: https://devcenter.heroku.com/articles/platform-api-reference
  - type: CompatibilityPolicy
    url: https://devcenter.heroku.com/articles/api-compatibility-policy
  - type: JSONSchema
    url: https://api.heroku.com/schema
  - type: Scope
    data:
      surfaces:
      - REST
      publisher: Heroku (Salesforce)
      license: documentation under Heroku terms
      status: living
- aid: style-guides:gitlab
  name: GitLab API Style Guide
  description: GitLab's developer-facing API style guide for the REST API (v4) and GraphQL API. Mandates Grape DSL parameter
    validation, Entity-based response payloads, Title Case summary verbs aligned to HTTP method, deprecation markers with
    migration guidance, and PATCH vs. PUT semantics. CC BY-SA 4.0.
  humanURL: https://docs.gitlab.com/ee/development/api_styleguide.html
  baseURL: https://gitlab.com/api/v4/
  tags:
  - REST
  - GraphQL
  - GitLab
  - Grape
  properties:
  - type: StyleGuide
    url: https://docs.gitlab.com/ee/development/api_styleguide.html
  - type: GraphQLStyleGuide
    url: https://docs.gitlab.com/ee/development/api_graphql_styleguide.html
  - type: License
    url: https://creativecommons.org/licenses/by-sa/4.0/
  - type: Scope
    data:
      surfaces:
      - REST
      - GraphQL
      publisher: GitLab
      license: CC BY-SA 4.0
      status: living
  - url: graphql/style-guides-graphql.md
    type: GraphQL
- aid: style-guides:kubernetes
  name: Kubernetes API Conventions
  description: The Kubernetes API conventions document, maintained by SIG Architecture. Defines the "kind / apiVersion" object
    envelope, spec/status separation, resourceVersion-based optimistic concurrency, list semantics, label and selector validation,
    and the patterns used by every Kubernetes-native API (and by extension every CRD).
  humanURL: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
  baseURL: https://github.com/kubernetes/community/
  tags:
  - REST
  - Kubernetes
  - SIG Architecture
  - CRD
  properties:
  - type: StyleGuide
    url: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
  - type: License
    url: https://github.com/kubernetes/community/blob/master/LICENSE
  - type: Scope
    data:
      surfaces:
      - REST
      publisher: Kubernetes / CNCF
      license: Apache-2.0 (repo)
      status: living
- aid: style-guides:ietf-httpapi
  name: IETF HTTPAPI Working Group Drafts and RFCs
  description: The IETF httpapi Working Group is producing the cross-vendor vocabulary that style guides increasingly cite
    normatively. Includes RFC 9457 Problem Details for HTTP APIs, RFC 9652 Link-Template, RFC 9745 Deprecation header, RFC
    9727 api-catalog, plus active drafts on privacy and digest problem types and recently-expired drafts on Idempotency-Key
    and RateLimit header fields.
  humanURL: https://datatracker.ietf.org/wg/httpapi/documents/
  baseURL: https://datatracker.ietf.org/
  tags:
  - IETF
  - HTTP
  - REST
  - Problem Details
  - RateLimit
  - Deprecation
  properties:
  - type: StandardsTrack
    url: https://datatracker.ietf.org/wg/httpapi/documents/
  - type: RFC
    url: https://www.rfc-editor.org/rfc/rfc9457
    name: RFC 9457 Problem Details for HTTP APIs
  - type: RFC
    url: https://www.rfc-editor.org/rfc/rfc9652
    name: RFC 9652 The Link-Template HTTP Header Field
  - type: RFC
    url: https://www.rfc-editor.org/rfc/rfc9745
    name: RFC 9745 The Deprecation HTTP Response Header Field
  - type: RFC
    url: https://www.rfc-editor.org/rfc/rfc9727
    name: RFC 9727 api-catalog Well-Known URI
  - type: ExpiredDraft
    url: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
    name: draft-ietf-httpapi-idempotency-key-header
  - type: ExpiredDraft
    url: https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/
    name: draft-ietf-httpapi-ratelimit-headers
  - type: Scope
    data:
      surfaces:
      - HTTP
      - REST
      publisher: IETF
      license: IETF Trust (RFC) / public
      status: mixed (RFCs + active drafts + expired drafts)
common:
- type: DomainSecurity
  url: security/style-guides-domain-security.yml
- type: JSONSchema
  url: https://raw.githubusercontent.com/api-evangelist/style-guides/main/json-schema/style-guide-rule-schema.json
- type: JSONLD
  url: https://raw.githubusercontent.com/api-evangelist/style-guides/main/json-ld/style-guides-context.jsonld
- type: Vocabulary
  url: https://raw.githubusercontent.com/api-evangelist/style-guides/main/vocabulary/style-guides-vocabulary.yml
- type: Examples
  url: https://github.com/api-evangelist/style-guides/tree/main/examples
- type: DeveloperPortal
  url: https://developer.apievangelist.com/
- type: Network
  url: https://developer.apievangelist.com/network/
- type: GitHubOrganization
  url: https://github.com/api-evangelist
- type: RelatedTopic
  url: https://github.com/api-evangelist/design-standards
- type: RelatedTopic
  url: https://github.com/api-evangelist/rules
- type: RelatedTopic
  url: https://github.com/api-evangelist/policies
maintainers:
- FN: Kin Lane
  email: info@apievangelist.com
  X-github: kinlane

API Style Guides

APIs 11

GraphQL 1

Semantic Vocabularies 1

Spectral Rules 1

JSON Schema 1

Examples 18

Security Posture 1

Get Started 1

Documentation 1

Design & Contract 2

Build 2

Access & Security 1

Other 4

Source (apis.yml)