# HTTP Client

Your GreenLightning app can also function as a HTTP client for sending REST requests, etc... to other servers and parsing the response.

Please refer to the [GreenLightning-API](https://github.com/oci-pronghorn/GreenLightning-API) repo for more examples like this one.

Use the code below to get started with creating a HTTP client. 

## Example

This is an example GreenLightning App in which we want to hit up a server somewhere containing JSON weather data (or see [Simple REST Server](/greenlightning/chapter-1-getting-started-with-greenlightning/simple-rest-server.md) on how to build your own REST service). 

In this example, we build a simple app that performs a GET request to a local server which servers a static JSON file containing "wather data":

First, we create our client. We specify that we are also acting as a HTTP client on line 8, and create the client instance on line 11. We also declare the JSON fields we care about.

{% code title="Client.java" %}

```java
public class Client implements GreenApp
{
    private ClientHostPortInstance weatherSession;

    @Override
    public void declareConfiguration(Builder config) {
        // In this example, we have TLS enabled.
        HTTPClientConfig netClientConfig = config.useNetClient();

        // We directly parse JSON of the current session.
        weatherSession = netClientConfig.createHTTP1xClient("127.0.0.1", 443)
                .parseJSON()
                    .stringField("condition", WeatherFields.WEATHER_CONDITIONS)
                    .decimalField("temperature", WeatherFields.TEMP_KELVIN)
                .finish();
    }

    @Override
    public void declareBehavior(GreenRuntime runtime) {
        // Add the weather behavior here.
        runtime.addResponseListener(new WeatherBehavior(runtime, weatherSession))
                .acceptHostResponses(weatherSession);
    }
    
}
```

{% endcode %}

Create the field identifiers:

{% code title="WeatherFields.java" %}

```java
package com.ociweb;

public enum WeatherFields {
    WEATHER_CONDITIONS, TEMP_KELVIN
}
```

{% endcode %}

`WeatherBehavior` will be responsible for sending out the request and receiving the response. We use a `HTTPRequestService` to do this.

{% code title="WeatherBehavior.java" %}

```java
public class WeatherBehavior implements HTTPResponseListener, StartupListener, ShutdownListener {
    // Keep track of active session for get request.
    private ClientHostPortInstance session;
    
    // This will actually perform the request.
    private final HTTPRequestService clientService;

    public WeatherBehavior(GreenRuntime runtime, ClientHostPortInstance session) {
        // Create the request service.
        clientService = runtime.newCommandChannel().newHTTPClientService();
        this.session = session;
    }

    @Override
    public void startup() {
        // Send out the request on startup.
        clientService.httpGet(session, "/api/weather");
    }
    
    @Override
    public boolean acceptShutdown() {
        // Close the session when shutting down.
        return clientService.httpClose(session);
    }

    @Override
    public boolean responseHTTP(HTTPResponseReader reader) {
        // We need to open the payload data.
        reader.openPayloadData( (r)-> {
            // Since we want to directly parse the fields, it needs to be structured.
            StructuredReader s = r.structured();

            // Read the fields from JSON.
            double tempKelvin = s.readDecimalAsDouble(WeatherFields.TEMP_KELVIN);
            String conditions = s.readText(WeatherFields.WEATHER_CONDITIONS);

            // Do whatever you'd like with the data here, this is just a short example.
            // Usually, you would use a PubSub service to send this information back to
            // another behavior.
            System.out.println(conditions + ", " + tempKelvin);
        });

        return true;
    }
}
```

{% endcode %}

## �Methods

### HTTPRequestService.httpGet(ClientHostPortInstance session, String route, optional: HeaderWritable headers)

Sends a GET request to the route (host is defined in session). Optional headers can be written.

{% code title="" %}

```java
clientService.httpGet(session, "/api/weather");
```

{% endcode %}

{% code title="" %}

```java
clientService.httpGet(session, "/shopping", 
                header -> header.write(HTTPHeaderDefaults.SET_COOKIE, "__Secure-ID=123; Secure; Domain=example.com"));
```

{% endcode %}

You can also write multiple headers:

```java
clientService.httpGet(session, "/shopping",
        header -> {
            header.write(HTTPHeaderDefaults.SET_COOKIE, "__Secure-ID=123; Secure; Domain=example.com");
            header.write(HTTPHeaderDefaults.DATE, "Wed, 21 Oct 2018 07:28:00 GMT");
});
```

### HTTPRequestService.httpPost(ClientHostPortInstance session, String route, Writable payload)

Sends a POST request to the route (host is defined in session). Optional headers can be written.

{% code title="" %}

```java
clientService.httpPost(session, "/post_comment", payload -> {
            payload.writeUTF("This is a comment.");
});
```

{% endcode %}

### HTTPRequestService.httpPost(ClientHostPortInstance session, String route, HeaderWritable headers, Writable payload)

Sends a POST request to the route (host is defined in session) with custom headers.

{% code title="" %}

```java
clientService.httpPost(session, "/post_comment",
                header-> header.write(HTTPHeaderDefaults.DATE, "Wed, 21 Oct 2018 07:28:00 GMT"),
                payload -> {
                    payload.writeUTF("This is a comment.");
                });
```

{% endcode %}

### HTTPRequestService.httpClose(ClientHostPortInstance session)

Closes the current session. Usually, you want to call this in the `acceptShutdown()` method using a `ShutdownListener` in your behavior.

```java
@Override
public boolean acceptShutdown() {
    return clientService.httpClose(session);
}
```

�


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://oci-pronghorn.gitbook.io/greenlightning/chapter-6-clients/http-client.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.