Glossary
Key terms and concepts for Terraform providers, API platforms, and infrastructure management.
Breaking Change
A modification that removes or alters existing behavior in a way that requires users to update their code. In Terraform, this typically means a field removal, type change, or a previously optional field becoming required. In APIs, it can mean removing an endpoint, changing a response schema, or making a required parameter.
ForceNew
A Terraform schema attribute flag indicating that changing this field value will destroy and recreate the resource rather than updating it in-place. This is critical for production planning as it causes downtime.
Deprecation
A notice that a resource, field, or feature will be removed in a future version. Deprecated items still work but should be replaced with recommended alternatives to avoid future breaking changes.
State Drift
When the actual infrastructure doesn't match the Terraform state file. This can happen after manual changes, failed applies, or provider upgrades that change how resources are read.
Terraform Plan
A command that shows what changes Terraform will make to match your configuration. Essential before any upgrade to verify no unexpected resource recreations or modifications.
Terraform Apply
A command that executes the planned changes to create, update, or destroy infrastructure. Should always be preceded by a plan review, especially after provider upgrades.
Provider
A Terraform plugin that interfaces with a specific infrastructure platform (e.g., AWS, Google Cloud, Azure). Providers translate HCL configuration into API calls.
Resource
A Terraform configuration block representing a single infrastructure object (e.g., aws_s3_bucket, aws_lambda_function). Resources have attributes that map to the provider's API.
Data Source
A read-only Terraform block that fetches information from the provider without creating infrastructure. Used to reference existing resources or computed values.
Migration
The process of updating Terraform configurations and state to work with a new provider version. May involve renaming fields, updating resource types, or running state manipulation commands.
Rollback
Reverting to a previous provider version by pinning the version constraint and restoring state from backup. Essential safety net when upgrades cause unexpected issues.
Severity Score
A numeric value assigned by Brief Stack that quantifies the impact of changes between provider versions. Calculated from: breaking (+20), security (+20), deprecation (+10), behavior (+5), feature (+2).
OpenAPI Specification
A standard, language-agnostic format for describing RESTful APIs. OpenAPI specs define endpoints, request/response schemas, authentication, and more. Brief Stack uses OpenAPI diffs to detect API changes between versions.
Schema Diff
A structured comparison between two versions of a schema — whether Terraform provider schemas or OpenAPI specifications. Schema diffs identify added, removed, and modified fields, endpoints, and types at a granular level.
API Versioning
The practice of maintaining multiple versions of an API to ensure backwards compatibility. Common strategies include URL versioning (v1, v2), header versioning, and date-based versioning (used by Stripe and GitHub).
Backwards Compatibility
The ability of a system to accept input from earlier versions without modification. A backwards-compatible change means existing integrations continue to work. Adding optional fields or new endpoints is typically backwards-compatible; removing fields is not.
Rate Limiting
A mechanism that restricts the number of API requests a client can make within a time window. Rate limiting protects API servers from overuse and ensures fair access. Changes to rate limits can significantly impact integrations.
Webhook
A mechanism where an API sends real-time HTTP POST notifications to a specified URL when certain events occur. Webhooks are an alternative to polling and are commonly used by platforms like Stripe, GitHub, and Slack.
Pagination
A technique for dividing large API response sets into discrete pages. Common patterns include offset-based, cursor-based, and keyset pagination. Changes to pagination behavior can be breaking for API consumers.
Idempotency
The property of an operation where performing it multiple times produces the same result as performing it once. Critical in payment APIs (e.g., Stripe's idempotency keys) to prevent duplicate charges during retries.