The API category provides a solution for making HTTP requests to REST and GraphQL endpoints. For building GraphQL APIs please visit the [GraphQL Getting Started](/lib/graphqlapi/getting-started) section of our documentation.

The REST API category can be used for creating signed requests against Amazon API Gateway when the API Gateway Authorization is set to `AWS_IAM`. 

> Ensure you have [installed and configured the Amplify CLI and library](/cli/start/install).

## Automated Setup: Create new REST API

Run the following command in your project's root folder:

```bash
amplify add api
```

Select `REST` as the service type.

```console
? Please select from one of the below mentioned services
  GraphQL
❯ REST
```

The CLI will prompt several options to create your resources. With the provided options you can create:
- REST endpoints that triggers Lambda functions
- REST endpoints which enables CRUD operations on an Amazon DynamoDB table

During setup you can use existing Lambda functions and DynamoDB tables or create new ones by following the CLI prompts. After your resources have been created update your backend with the `push` command:

```bash
amplify push
```

A configuration file called `aws-exports.js` will be copied to your configured source directory, for example `./src`.

### Configure your application

import js0 from '/src/fragments/lib/common/js/import_configuration.mdx'

<Fragments fragments={{ js: js0 }} />

import rn1 from '/src/fragments/lib/common/react-native/import_configuration.mdx'

<Fragments fragments={{ 'react-native': rn1 }} />

```javascript
import { Amplify, API } from 'aws-amplify';
import awsconfig from './aws-exports';

Amplify.configure(awsconfig);
```

## Manual Setup: Reference existing REST API

For manual configuration you need to provide your AWS Resource configuration and optionally configure authentication.

```javascript
import { Amplify, API } from 'aws-amplify';

Amplify.configure({
  // OPTIONAL - if your API requires authentication 
  Auth: {
    identityPoolId: 'XX-XXXX-X:XXXXXXXX-XXXX-1234-abcd-1234567890ab', // REQUIRED - Amazon Cognito Identity Pool ID
    region: 'XX-XXXX-X', // REQUIRED - Amazon Cognito Region
    userPoolId: 'XX-XXXX-X_abcd1234', // OPTIONAL - Amazon Cognito User Pool ID
    userPoolWebClientId: 'a1b2c3d4e5f6g7h8i9j0k1l2m3', // OPTIONAL - Amazon Cognito Web Client ID (26-char alphanumeric string)
  },
  API: {
    endpoints: [
      {
        name: "MyAPIGatewayAPI",
        endpoint: "https://1234567890-abcdefgh.amazonaws.com"
      },
      {
        name: "MyCustomCloudFrontApi",
        endpoint: "https://api.my-custom-cloudfront-domain.com",

      }
    ]
  }
});
```

### AWS Regional Endpoints

<!-- TODO Rewrite why do we have this here if we do NOT recommend it? -->

You can utilize regional endpoints by passing in the *service* and *region* information to the configuration. See [AWS Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html). The example below defines a [Lambda invocation](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) in the `us-east-1` region:

```javascript
API: {
  endpoints: [
    {
      name: "MyCustomLambda",
      endpoint: "https://lambda.us-east-1.amazonaws.com/2015-03-31/functions/yourFuncName/invocations",
      service: "lambda",
      region: "us-east-1"
    }
  ]
}
```
<Callout warning>

The above example **IS NOT A RECOMMENDED ARCHITECTURE** and we highly recommend you leverage AWS AppSync or API Gateway as the endpoint to invoke your Lambda functions. 

</Callout>

 <Callout>

 **Configuring Amazon Cognito Regional Endpoints:** To call regional service endpoints, your Amazon Cognito role needs to be configured with appropriate access for the related service. See [AWS Cognito Documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/iam-roles.html) for more details.

 </Callout>