Amplify CLI API Category Plugin

3.3.5 verified Tue Apr 21 auth: no javascript

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.

Common errors

error GraphQL schema validation failed ↓

cause The `schema.graphql` file contains syntax errors, invalid directives, or conflicts with Amplify's GraphQL Transformer rules.

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.

error An error occurred during the push operation: Your GraphQL Schema is using "@key" directive from an older version of the GraphQL Transformer. ↓

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).

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.

error Stack named 'amplify-<projectname>-api-<envname>' already exists ↓

cause A CloudFormation stack for your API environment exists but is in an unrecoverable state, or a previous deployment failed, leaving residual resources.

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.

error Error: There are no categories configured in the project. Use 'amplify add <category>' to add a category. ↓

cause The Amplify project has not been properly initialized or the `amplify init` command was not run from the project root.

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.

Warnings

breaking 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. ↓

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.

gotcha 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. ↓

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.

gotcha 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. ↓

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.

deprecated The `amplify rebuild api` command, used in GraphQL Transformer v1, is deprecated and no longer reliably works with newer transformer 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`.

Install

npm install amplify-category-api

yarn add amplify-category-api

pnpm add amplify-category-api

Imports

No direct programmatic imports for application code
wrong
```
import { addApi } from '@aws-amplify/amplify-category-api';
const apiCategory = require('@aws-amplify/amplify-category-api');
```
correct
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+).

Quickstart

Demonstrates initializing an Amplify project, adding a GraphQL API using the CLI, and deploying it to the AWS cloud.

npx create-react-app my-amplify-app
cd my-amplify-app
amplify init # Follow prompts to initialize a new Amplify project

# Add a GraphQL API
amplify add api
  # Choose 'GraphQL'
  # Choose 'Authorize and configure with AWS IAM (recommended for multi-user apps)'
  # Choose 'Single object with fields (e.g., "Todo")' or 'Blank schema'
  # Edit schema.graphql if desired (e.g., add more @model types)

# Deploy the API to the cloud
amplify push # Confirm changes and deploy