To invoke an endpoint, you need to set `apiName`, `path` and `headers` parameters, and each method returns a Promise. Under the hood the API category utilizes [Axios](https://github.com/axios/axios) to execute the HTTP requests. API status code response > 299 are thrown as an exception. If you need to handle errors managed by your API, work with the `error.response` object.

## GET requests

```javascript
const apiName = 'MyApiName';
const path = '/path';
const myInit = {
  headers: {}, // OPTIONAL
  response: true, // OPTIONAL (return the entire Axios response object instead of only response.data)
  queryStringParameters: {
    name: 'param' // OPTIONAL
  }
};

API.get(apiName, path, myInit)
  .then((response) => {
    // Add your code here
  })
  .catch((error) => {
    console.log(error.response);
  });
```

Example with async/await

```javascript
function getData() {
  const apiName = 'MyApiName';
  const path = '/path';
  const myInit = {
    headers: {} // OPTIONAL
  };

  return API.get(apiName, path, myInit);
}

(async function() {
  const response = await getData();
})();
```

## GET requests with query parameters

To use query parameters with `get` method, you can pass them in `queryStringParameters` parameter in your method call:

```javascript
const items = await API.get('myCloudApi', '/items', {
  queryStringParameters: {
    order: 'byPrice'
  }
});
```

## HEAD

<!-- TODO Rewrite What is this for? -->

```javascript
const apiName = 'MyApiName'; // replace this with your api name.
const path = '/path'; //replace this with the path you have configured on your API
const myInit = {
  headers: {} // OPTIONAL
};

API.head(apiName, path, myInit).then((response) => {
  // Add your code here
});
```

Example with async/await:

```javascript
function head() {
  const apiName = 'MyApiName';
  const path = '/path';
  const myInit = {
    headers: {} // OPTIONAL
  };

  return API.head(apiName, path, myInit);
}

(async function() {
  const response = await head();
})();
```

## Accessing query parameters & body in Lambda proxy function

> To learn more about Lambda Proxy Integration, please visit [Amazon API Gateway Developer Guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-api-as-simple-proxy-for-lambda.html).

If you are using a REST API which is generated with Amplify CLI, your backend is created with Lambda Proxy Integration, and you can access your query parameters & body within your Lambda function via the _event_ object:

```javascript
exports.handler = function(event, context, callback) {
  console.log(event.queryStringParameters);
  console.log('body: ', event.body);
};
```

Alternatively, you can update your backend file which is located at `amplify/backend/function/[your-lambda-function]/app.js` with the middleware:

```javascript
const awsServerlessExpressMiddleware = require('aws-serverless-express/middleware');
app.use(awsServerlessExpressMiddleware.eventContext());
```

Accessing Query Parameters with Serverless Express

In your request handler use `req.apiGateway.event` or `req.query`:

```javascript
app.get('/items', function(req, res) {
  const query = req.query;
  // or
  // const query = req.apiGateway.event.queryStringParameters
  res.json({
    event: req.apiGateway.event, // to view all event data
    query: query
  });
});
```

Then you can use query parameters in your path as follows:

```javascript
API.get('sampleCloudApi', '/items?q=test');
```

## Custom response types

By default, calling an API with AWS Amplify parses a JSON response. If you have a REST API endpoint which returns, for example, a file in Blob format, you can specify a custom response type using the `responseType` parameter in your method call:

```javascript
let file = await API.get('myCloudApi', '/items', {
  responseType: 'blob'
});
```

Allowed values for `responseType` are "arraybuffer", "blob", "document", "json" or "text"; and it defaults to "json" if not specified. See the [documentation](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/responseType) for more information.