{"id":15950,"library":"amplify-category-api","title":"Amplify CLI API Category Plugin","description":"The `@aws-amplify/amplify-category-api` package is an internal plugin for the AWS Amplify Command Line Interface (CLI). It empowers developers to create, configure, and manage both GraphQL (AWS AppSync) and REST (Amazon API Gateway) API resources within their Amplify projects. It's not a library for direct programmatic consumption but rather a core component of the `amplify` CLI toolchain, which currently operates at major version `14.x.x` for the CLI itself. This specific plugin's latest stable version is `5.15.3`. The Amplify CLI maintains a frequent release cadence, often with minor updates and bug fixes for its various categories. Key differentiators include its declarative API modeling with GraphQL Schema Definition Language (SDL) and automatic CloudFormation generation, alongside capabilities for local mocking and team environment management.","status":"active","version":"3.3.5","language":"javascript","source_language":"en","source_url":"https://github.com/aws-amplify/amplify-cli","tags":["javascript"],"install":[{"cmd":"npm install amplify-category-api","lang":"bash","label":"npm"},{"cmd":"yarn add amplify-category-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add amplify-category-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is an internal plugin for the AWS Amplify CLI and is not designed for direct programmatic import or usage in user applications. Developers interact with its functionality exclusively through the `amplify api` command-line interface. For programmatic access to Amplify APIs within your application, use `@aws-amplify/api` (v6+).","wrong":"import { addApi } from '@aws-amplify/amplify-category-api';\nconst apiCategory = require('@aws-amplify/amplify-category-api');","symbol":"No direct programmatic imports for application code","correct":""}],"quickstart":{"code":"npx create-react-app my-amplify-app\ncd my-amplify-app\namplify init # Follow prompts to initialize a new Amplify project\n\n# Add a GraphQL API\namplify add api\n  # Choose 'GraphQL'\n  # Choose 'Authorize and configure with AWS IAM (recommended for multi-user apps)'\n  # Choose 'Single object with fields (e.g., \"Todo\")' or 'Blank schema'\n  # Edit schema.graphql if desired (e.g., add more @model types)\n\n# Deploy the API to the cloud\namplify push # Confirm changes and deploy","lang":"bash","description":"Demonstrates initializing an Amplify project, adding a GraphQL API using the CLI, and deploying it to the AWS cloud."},"warnings":[{"fix":"Always consult the official Amplify CLI migration guides for your specific version. Utilize `amplify migrate api` for automated schema migration, and manually review and update `@auth`, `@key`, and relationship directives.","message":"Upgrading the Amplify CLI (especially across major versions) often introduces breaking changes, particularly concerning the GraphQL Transformer (e.g., v1 to v2 migration). Directives like `@key` were replaced by `@primaryKey` and `@index`, and authorization rules (`@auth`) shifted to a 'deny-by-default' approach requiring explicit configuration.","severity":"breaking","affected_versions":">=10.0.0 (Amplify CLI overall)"},{"fix":"Manage all Amplify-generated API resources through the CLI. If manual changes are unavoidable, explore Amplify's 'Overrides' feature (CLI v7+) or consider defining custom resources to prevent drift.","message":"Manual modifications to Amplify-provisioned API resources directly in the AWS console (e.g., AppSync resolvers, DynamoDB tables) can lead to CloudFormation drift. Subsequent `amplify push` operations might overwrite these manual changes or fail due to state inconsistencies.","severity":"gotcha","affected_versions":"*"},{"fix":"Leverage `amplify mock api` for local development and testing of GraphQL APIs and resolvers, enabling faster feedback loops without cloud deployments. For significant schema changes, consider using feature branches and reviewing `amplify status` before pushing.","message":"Frequent `amplify push` operations during active API development, especially with complex GraphQL schemas, can be slow. This can hinder rapid iteration due to the time required for CloudFormation deployments.","severity":"gotcha","affected_versions":"*"},{"fix":"Instead of `amplify rebuild api`, use `amplify push` after schema changes. If encountering persistent issues, a common workaround is to back up your schema, `amplify remove api`, `amplify push`, then `amplify add api` with the backed-up schema, followed by another `amplify push`.","message":"The `amplify rebuild api` command, used in GraphQL Transformer v1, is deprecated and no longer reliably works with newer transformer versions.","severity":"deprecated","affected_versions":"Amplify CLI >=7.0.0 (approximately)"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Review `amplify/backend/api/<api-name>/schema.graphql` for errors. Use an IDE with GraphQL syntax highlighting and refer to Amplify's GraphQL Transformer documentation for correct directive usage. Running `amplify api gql-compile` can help identify specific issues.","cause":"The `schema.graphql` file contains syntax errors, invalid directives, or conflicts with Amplify's GraphQL Transformer rules.","error":"GraphQL schema validation failed"},{"fix":"Migrate your GraphQL schema to Transformer v2 using `amplify migrate api`. Update `@key` directives to `@primaryKey` or `@index` as appropriate, and review `@auth` rules for the new 'deny-by-default' behavior.","cause":"Your project is using an older GraphQL schema incompatible with the current Amplify CLI's GraphQL Transformer (e.g., attempting to use `@key` with Transformer v2).","error":"An error occurred during the push operation: Your GraphQL Schema is using \"@key\" directive from an older version of the GraphQL Transformer."},{"fix":"Check the AWS CloudFormation console for your Amplify project's stacks. If a stack is stuck in a `ROLLBACK_COMPLETE` or `UPDATE_ROLLBACK_FAILED` state, you may need to manually delete it. If you are confident, `amplify push --force` can sometimes resolve minor inconsistencies, but this should be used with caution.","cause":"A CloudFormation stack for your API environment exists but is in an unrecoverable state, or a previous deployment failed, leaving residual resources.","error":"Stack named 'amplify-<projectname>-api-<envname>' already exists"},{"fix":"Ensure you are in the root directory of your Amplify project and run `amplify init` if this is a new project, or `amplify pull` if you are cloning an existing project. Then, use `amplify add api` to configure your API.","cause":"The Amplify project has not been properly initialized or the `amplify init` command was not run from the project root.","error":"Error: There are no categories configured in the project. Use 'amplify add <category>' to add a category."}],"ecosystem":"npm"}