---
schema_version: "1"
id: d33e31be6906a53a11e37d69f62dccbc680c5a3ebf59bef5f245343f47e59817
title: Consume Data from an API
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-runtime/4.11/consume-data-from-an-api.md
canonical_url: https://docs.mulesoft.com/mule-runtime/4.11/consume-data-from-an-api
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 99551148e51ffcf4d271903320b993746e4adc4b4ddf82723f64c26262cb88da
description: MuleSoft Documentation Site
release: "4.11"
latest: false
---
---
product: Mule Runtime
version: 4.11
---

# Consume Data from an API

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

After you build your application, you can start consuming data from an API. Review the following
processes to consume data from a SOAP or REST API.

## Consume Data from a SOAP API

To consume data from a SOAP API that does not have its own Anypoint Connector, configure Anypoint
Connector for Web Service Consumer (Web Service Consumer Connector).  
Using the host, port, and address metadata retrieved from the API’s WSDL file, the connector
provides the connection configuration you need for consuming a service from within your Mule
application:

See [Web Service Consumer Connector](https://docs.mulesoft.com/web-service-consumer-connector/latest/) for details.

## Consume Data from a REST API

The following process focuses on configuring the HTTP Request Connector to call the REST API. It
helps you to understand the basic anatomy of how a Mule application consumes a REST API, the minimum
configuration required, how to consume examples, how to configure dynamic requests, how to manage
HTTP Content-Type and encoding, and how to work with custom headers and security requirements.

To consume data from a REST API from within a Mule application, you can configure Anypoint Connector
for HTTP Request (HTTP Request Connector).

If you connect to the same REST API many times or work with an API that has complex authentication
protocols, consider [developing your own connector using the Mule SDK](https://docs.mulesoft.com/mule-sdk/latest/).
Check whether a connector already exists in
[Anypoint Exchange](https://anypoint.mulesoft.com/exchange/) for the API you want to connect to. You
can search in Exchange through Anypoint Studio’s Mule Palette.

## Basic Anatomy

A Mule application consuming a REST API consists of the following:

- One or more message processors configured to build your request

- An HTTP request operation configured to call the REST API

- One or more message processors configured to accept and process the response

![Consuming REST API Flow](/mulesoft/current/en-us/mule-runtime/4.11/_images/mruntime-consume-rest-api-flow.png)

Figure 1. Consuming REST API Flow.

You configure the portions of the application that build the request and process the response.

## Minimum Configuration

The REST API you are consuming must have a [RAML](https://raml.org/) file that describes the API, so
that the HTTP connector proactively presents you with smart suggestions.

In the RAML file, you define the following:

- Authentication

- A base URI for configuring the outbound HTTP endpoint

- Scope

  Based on authentication credentials, the application can limit calls to only GET requests on
  certain resources, for example, or otherwise limit access to a resource.

- Resources

  You must configure the path of the resources for the outbound HTTP endpoint.

- Methods

  You can accept POST as the default method for the HTTP outbound endpoint, or you can change this
  default to the method supported by your resource.

- Input validation

  For POST and PUT calls, the API almost always requires that the input format, such as JSON or XML,
  match its schema.

In Mule runtime engine, you can define or configure the following:

- Output format

  After the HTTP request operation, your flow must include message processors to accept the response
  from the API and translate the response into a useable format.

- Redirects

  If the API uses redirects, enable redirects in your HTTP request operation.

- Timeout

- Headers for methods

  POST, PUT, and DELETE requests almost always require headers.

- URI and Query Parameters

- Error handling

See [HTTP Connector documentation](https://docs.mulesoft.com/http-connector/latest/#input-sources) for more information
about how to configure the request operation.

### Consume REST API Example

The following example consumes the
[JSONPlaceholder API](https://jsonplaceholder.typicode.com/todos/1). The example shows only the
configuration of the HTTP Request Connector, and to make it work, you must configure at least one
Mule event source to trigger a message in the flow and at least one message processor to accept the
response. See [REST API Examples documentation](https://docs.mulesoft.com/mule-runtime/4.11/rest-api-examples) for more information.

In this API example:

- The API doesn’t require authentication.

- The base URL is `jsonplaceholder.typicode.com`.

- The API is a mock API for development purposes.

- The sample API requests show that to get information about user with `id=1` the request must be:

https://jsonplaceholder.typicode.com/users/1

The parts of the URL are as follows:

- Protocol: `http`

- API Base URL: `jsonplaceholder.typicode.com`

- Resource path: `/users/1`

- Query Parameters: None, in this case.

To implement this call in your Mule application, configure your HTTP request operation.

### Configure HTTP Request Operation in Anypoint Studio

1.  From the Mule Palette in Studio, add an HTTP Request Connector to your application.

2.  In the HTTP Request Configuration window, provide `jsonplaceholder.typicode.com` as the value
    for **Host**.

3.  Set the **Port** value to 80.

4.  Click **OK**:

![An HTTP Request configuration with Host and Port](/mulesoft/current/en-us/mule-runtime/4.11/_images/mruntime-consume-rest-api-configuration-1.png)

Figure 2. HTTP Request configuration with Host and Port.

5.  Navigate to the Request section from the HTTP Request operation’s properties editor > General
    tab and add `/users/1` in the **Path** field.  
    Specifying this path completes the URL that you began to identify by specifying the host in the
    first step.

6.  Select a method from the **Method** drop-down list (in this example, `GET`).

7.  Save your application.

![An HTTP Request GET Method and Path](/mulesoft/current/en-us/mule-runtime/4.11/_images/mruntime-consume-rest-api-configuration-2.png)

Figure 3. HTTP Request GET Method and Path.

### Configure HTTP Request Operation in XML

The following XML code shows the configuration of the HTTP Request operation for the example:

```xml
<http:request-config name="HTTP_Request_configuration">
    <http:request-connection host="jsonplaceholder.typicode.com" />
  </http:request-config>

<flow name="basic_tutorialFlow1">

    <...>

    <http:request method="GET" doc:name="Request" config-ref="HTTP_Request_configuration" path="/users/1"/>
</flow>
```

### Example JSON Response

For the JSONPlaceholder API example, the JSON response has the following structure:

```json
{
  "userId": 1,
  "id": 3,
  "title": "fugiat veniam minus",
  "completed": false
}
```

You can transform the data in the **Advanced** tab of the HTTP Request operation. You can also
define the target variable, which by default is the Payload.

If this API has an associated RAML file, you can reference it in the configuration element of the
connector. With that in place, after you select the verb and asset to call, Studio exposes the
metadata corresponding to the output. Integration with other elements in a flow is simplified.

## Configure Dynamic Requests with DataWeave Expressions

Most use cases require that you change the call to the API change dynamically based on data in the
message. You can configure these dynamic requests by using DataWeave expressions.

In the configuration examples documented in "Consume REST API Example", the request was hardcoded in
the URL:

https://jsonplaceholder.typicode.com/users/1

In the following GET request example, the call instructs Mule runtime engine to extract the user ID
from the payload of the message, using the DataWeave expression `#[payload.user_id]`.

https://jsonplaceholder.typicode.com/users/#\[payload.user\_id\]

### Configure Dynamic Requests in Anypoint Studio

To perform the same operation by using Anypoint Studio, modify the path configuration with the
desired DataWeave expression: in this case `#['/users/' ++ payload.user_id]`.

![A configure Dynamic Requests with DataWeave expressions in Path field](/mulesoft/current/en-us/mule-runtime/4.11/_images/mruntime-consume-rest-api-configuration-3.png)

Figure 4. Configure Dynamic Requests with DataWeave expressions in Path field.

You can also configure dynamic requests for the query or URI parameters, or for the HTTP method.
Additionally, you can use [Configuration Properties](https://docs.mulesoft.com/mule-runtime/4.11/configuring-properties) to set any of these
dynamic requests.

### Configure Dynamic Requests in XML

The following example code in XML, shows the configuration of dynamic requests:

```xml
  <http:request-config name="HTTP_Request_configuration">
    <http:request-connection host="jsonplaceholder.typicode.com" />
  </http:request-config>
  <flow name="basic_tutorialFlow1">
    <...>
    <set-payload value='#[{user_id: "10"}]'/>
    <http:request method="GET" config-ref="HTTP_Request_configuration" path="#['/users/' ++ payload.user_id]"/>
  </flow>
```

## HTTP Content-Type and Encoding

When you send a POST request, Mule runtime engine adheres to the following rules regarding
Content-Type and encoding of the body.

<table><colgroup><col> <col></colgroup><tbody><tr><td><p>Content</p></td><td><p>Rules</p></td></tr><tr><td><p>For a <code>String</code>, <code>char[]`</code>, <code>Reader</code>, or similar*</p></td><td><p>* If the endpoint has explicitly set encoding, Mule runtime engine uses that encoding. * If the endpoint does not have explicitly set encoding, Mule runtime engine determines the encoding from the message property <code>Content-Type</code>. * If the <code>Content-Type</code> message property is not set, Mule runtime engine uses the Mule Context default configuration. * For <code>Content-Type</code>, Mule runtime engine sends the message property <code>Content-Type</code>, but with the actual encoding set.</p></td></tr><tr><td><p>For binary content</p></td><td><div><div><p>Encoding is not relevant. Mule runtime engine sets <code>Content-Type</code> as follows:</p></div><div><ul><li><p>If the <code>Content-Type</code> property is set on the message, Mule runtime engine uses the defined content type.</p></li><li><p>If the <code>Content-Type</code> property is not set on the message, Mule runtime engine sets "application/octet-stream" as <code>Content-Type</code>.</p></li></ul></div></div></td></tr></tbody></table>

## Custom Headers

Some APIs require that you pass custom headers, such as your developer key, along with your
requests. As with the query parameters, you can also add headers to your request on the HTTP
Connector.  
For example, if the API you are consuming requires a developer key, then specify that key as a
header on your requests by using the header name `accessKey`.  
You can add a property to set custom headers by using Anypoint Studio.

### Custom Headers in Anypoint Studio

To set custom headers in Studio, review the following steps:

- In the HTTP Request operation’s properties editor, select the **Headers** tab.

- Click **Add**.

- Define **Name** and **Value**. Both can be defined using expressions or properties placeholders.

![A custom header configuration in Studio](/mulesoft/current/en-us/mule-runtime/4.11/_images/mruntime-consume-rest-api-configuration-4.png)

Figure 5. Configure Custom Headers in the HTTP Request operation’s properties editor.

## Security Requirements

If the API that you are calling requires complex authentication protocols, you can build your own
connector to consume it. Otherwise, you can meet API security requirements by setting basic
authentication credentials or configuring a global HTTPS connector.

### Basic Authentication

If the REST API that you are consuming requires you to supply basic authentication credentials, you
can provide them within the outbound HTTP endpoint configuration:

1.  In Studio, go to the HTTP Request configuration window.

2.  In Authentication, select **Basic Authentication**.

3.  Type your username and password. These can also be set as properties placeholders.

4.  Click **OK**.

    ![An HTTP Request showing settings for connection timeout, response buffer size, and TLS configuration](/mulesoft/current/en-us/mule-runtime/4.11/_images/mruntime-consume-rest-api-configuration-7.png)

### HTTPS Configuration

If you are consuming a REST API that requires that incoming requests arrive via HTTPS, you can
configure a global HTTPS Request connector in your Mule application, then reference the connector in
your request operation.  
In the following example, you configure the HTTPS Request connector, create a Java keystore file
(JKS) and [configure TLS](https://docs.mulesoft.com/mule-runtime/4.11/tls-configuration).

#### Configure the HTTP Request Connector for HTTPS

1.  In the HTTP Request Configuration window, navigate to General tab > Connection Configuration
    section.

2.  Select **HTTPS** for the **Protocol**.

3.  Click **OK**.

![An HTTP Request showing settings for protocol, host, port, and persistent connections configuration](/mulesoft/current/en-us/mule-runtime/4.11/_images/mruntime-consume-rest-api-configuration-5.png)

Figure 6. Configure HTTPS Request Connector.

#### Create a Keystore File

Using the Java keytool in the bin directory of the Java installation, create a keystore file to
certify the communication:

1.  Using the command line, navigate to the Java installation directory on your machine.

2.  Execute the following command:

keytool -genkey -alias mule -keyalg RSA -keystore keystore.jks

3.  When prompted, create two passwords and remember them for later use.  
    This action creates a `jks` file in the local directory called `keystore.jks`.

4.  Place your `keystore.jks` file:

    - If you use Studio, place the `keystore.jks` file into the `appname/src/main/resources`
      directory in Studio Package Explorer.

    - If you use XML in Mule runtime engine and want to use the file across multiple applications,
      place the file in the `MULE_HOME/conf` directory.

    - If you use XML in Mule runtime engine and want to use the file within this application, place
      the file in the `yourappname/src/main/resources` directory.

5.  Reference the keystore in a global HTTPS Request connector.  
    This connector is then referenced by the HTTP outbound endpoint within your flow.

#### Configure TLS

Follow these steps to configure TLS:

1.  In Studio, go to the Global Elements view.

2.  Select **Create** and search for "TLS Context".

3.  In the Key Store Configuration section, select a type of keystore configuration from the
    drop-down menu: for example, **JKS** (Java Key Store) which is the default type.

4.  For **Path**, specify the name of the keystore if you placed your keystore in the
    `appname/src/main/resources` directory; otherwise, specify `"/keystore.jks"`.

5.  For **Key Password**, and **Password**, enter the passwords that you created when creating your
    keystore file.

6.  Click **OK**.

![A TLS configuration showing settings for trust store and key store configurations](/mulesoft/current/en-us/mule-runtime/4.11/_images/mruntime-consume-rest-api-configuration-6.png)

Figure 7. Configure TLS.

7.  Go to the HTTP Request configuration window.

8.  In TLS Configuration, select **Global Reference** and the **TLS context** value that you created
    earlier.  
    You can also create the TLS context inline.

![An HTTP Request configuration including TLS and proxy details](/mulesoft/current/en-us/mule-runtime/4.11/_images/mruntime-consume-rest-api-configuration-8.png)

Figure 8. Configure TLS in HTTP Request Configuration.