API Spec

12 items tagged with "api-spec"

Filter by type:

Best Practices4

OpenAPI Specification Best Practices

Guidance for writing accurate, machine-readable OpenAPI documents that describe HTTP APIs and drive docs, client SDKs, mocks, and contract tests.

Best Practice

AsyncAPI Specification

A standard, machine-readable format for describing event-driven and message-based APIs across protocols like Kafka, MQTT, and AMQP, analogous to OpenAPI for REST.

Best Practice

Problem Details for HTTP APIs (RFC 9457)

An IETF standard JSON format for machine-readable HTTP error responses, defining fields like type, title, status, detail, and instance for consistent error handling.

Best Practice

JSON:API Specification

A convention for building JSON APIs that standardizes resource structure, relationships, pagination, filtering, and sparse fieldsets to reduce bikeshedding and over-fetching.

Anti-Patterns1

Anti-Pattern

Inconsistent API Naming and Conventions

An API where naming, casing, pluralization, error formats, and conventions vary across endpoints, raising the learning curve and integration errors.

Tutorials1

Tutorial

How to Document an API with OpenAPI

Write an OpenAPI specification, serve interactive docs, validate requests against the schema, and generate client code.

Playbooks3

Playbook

API-First Design Program Playbook

A program to establish API-first practices across teams using OpenAPI contracts, mock-driven development, and contract testing.

Playbook

AsyncAPI Messaging Standardization Playbook

A program to standardize asynchronous messaging contracts with AsyncAPI, schema governance, and contract testing across teams.

Playbook

REST API Versioning and Deprecation Playbook

A program to establish disciplined REST API versioning, backward compatibility, and graceful deprecation across a portfolio.

Checklists1

Checklist

REST to gRPC Migration Checklist

Plan a migration of internal service communication from REST to gRPC, covering contracts, compatibility, and rollout.

Comparisons1

Comparison

OpenAPI vs AsyncAPI

OpenAPI describes synchronous request/response HTTP APIs; AsyncAPI describes event-driven, message-based APIs over brokers and streams.

Glossaries1

Glossary

OpenAPI

OpenAPI is a language-agnostic specification for describing HTTP APIs in a machine-readable document, enabling shared contracts, documentation, and code generation.