getting_started_ktor_client.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic SYSTEM "https://resources.jetbrains.com/stardust/html-entities.dtd">

<topic xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/stardust/topic.v2.xsd"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       title="Creating a client application"
       id="getting_started_ktor_client">

    <microformat>
        <var name="example_name" value="tutorial-client-get-started"/>
        <include src="lib.xml" include-id="download_example"/>
    </microformat>

    <excerpt>
        Create your first client application for sending a request and receiving a response.
    </excerpt>

    <p>
        Ktor includes a multiplatform asynchronous HTTP client, which allows you to make requests and handle responses, extend its functionality with <a href="http-client_plugins.md">plugins</a>, such as authentication, JSON serialization, and so on.
        In this tutorial, we'll create a simple client application for sending a request and receiving a response.
    </p>

    <chapter title="Prerequisites" id="prerequisites">
        <include src="lib.xml" include-id="client_prerequisites"/>
    </chapter>

    <chapter title="Create a new project" id="new-project">
        <p>
            To try out a Ktor client in action, we'll create a Kotlin/JVM project.
            <a href="https://www.jetbrains.com/help/idea/run-for-the-first-time.html">Open IntelliJ IDEA</a>, and follow
            the steps below:
        </p>
        <procedure hide-from-structure="true">
            <step>
                <include src="lib.xml" include-id="new_project_idea"/>
            </step>
            <step>
                <p>
                    In the <control>New Project</control> wizard, choose <control>Kotlin Multiplatform</control> from the list on the left.
                </p>
            </step>
            <step>
                <p>
                    On the right pane, specify the following settings:
                </p>
                <img src="ktor_idea_new_gradle_project_settings.png" alt="Kotlin Multiplatform" border-effect="rounded" width="706"/>
                <list id="kotlin_app_settings">
                    <li>
                        <p>
                            <control>Name</control>: Specify a project name.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Location</control>: Specify a directory for your project.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Project Template</control>: Choose <emphasis>Console Application</emphasis> in the <emphasis>JVM</emphasis> group.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Build System</control>: Make sure that <control>Gradle Kotlin</control> is selected.
                        </p>
                    </li>
                </list>
                <p>
                    Click <control>Next</control>.
                </p>
            </step>
            <step>
                <p>
                    On the next page, change <control>Test framework</control> to <emphasis>None</emphasis>, click <control>Finish</control> and wait until IntelliJ IDEA generates a project and installs the dependencies.
                </p>
            </step>
        </procedure>
    </chapter>


    <chapter title="Add dependencies" id="add-dependencies">
        <p>
            Let's add dependencies required for a Ktor client.
        </p>
        <procedure hide-from-structure="true">
            <step>
                <p>
                    Open the <path>gradle.properties</path> file and add the following line to specify the Ktor version:
                </p>
                <code style="block" lang="kotlin" interpolate-variables="true">
                    ktor_version=%ktor_version%
                </code>
                <note id="eap-note">
                    <p>
                        To use the EAP version of Ktor, you need to add a <a href="server-dependencies.xml" anchor="repositories">Space repository</a>.
                    </p>
                </note>
            </step>
            <step>
                <p>
                    Open the <path>build.gradle.kts</path> file and add the following artifacts to the dependencies block:
                </p>
                <code style="block" lang="kotlin" src="snippets/tutorial-client-get-started/build.gradle.kts" lines="1-2,17-20"/>

                <p>
                    <code>ktor-client-core</code> is a core dependency that provides the main client functionality, while <code>ktor-client-cio</code> is a dependency for an <a href="http-client_engines.md">engine</a> processing network requests.
                </p>
            </step>
            <step>
                <p>
                    Click the <control>Load Gradle Changes</control> icon in the top right corner of the <path>build.gradle.kts</path> file to install newly added dependencies.
                </p>
                <img src="client_get_started_load_gradle_changes_name.png" alt="Load Gradle Changes" width="706"/>
            </step>
        </procedure>


    </chapter>


    <chapter title="Create a client" id="create-client">
        <p>
            Now we can add a client's code to the <path>src/main/kotlin/Main.kt</path> file:
        </p>
        <procedure hide-from-structure="true">
            <step>
                <p>
                    Replace the existing code in <path>Main.kt</path> with the following:
                </p>
                <code style="block" lang="kotlin">
                    import io.ktor.client.*
                    import io.ktor.client.engine.cio.*

                    fun main() {
                        val client = HttpClient(CIO)
                    }
                </code>
                <p>
                    A client is represented by the <a href="https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.client/-http-client/index.html">HttpClient</a> class.
                </p>
            </step>
            <step>
                <p>
                    To <a href="request.md">make a request</a> to a specific URL, we need to call a client's method corresponding to an HTTP verb, for example, <code>HttpClient.get</code>.
                    A <a href="response.md">response</a> will be received as a <code>HttpResponse</code> class object.
                </p>
                <code style="block" lang="kotlin">
                    import io.ktor.client.*
                    import io.ktor.client.engine.cio.*
                    import io.ktor.client.request.*
                    import io.ktor.client.statement.*

                    fun main() {
                        val client = HttpClient(CIO)
                        val response: HttpResponse = client.get("https://ktor.io/")
                    }
                </code>
            </step>
            <step>
                <p>
                    After adding the code above, the IDE shows the following error for the <code>get</code> function: <emphasis>Suspend function 'get' should be called only from a coroutine or another suspend function</emphasis>.
                </p>
                <img src="client_get_started_suspend_error.png" alt="Suspend function error" width="706"/>
                <p>
                    You can learn more about calling suspending functions from <a href="https://kotlinlang.org/docs/coroutines-basics.html">Coroutines basics</a>. In the next step, we'll make our <code>main</code> function suspending to fix this issue.
                </p>
            </step>
            <step>
                <p>
                    Click the red bulb and choose <control>Make main suspend</control>.
                </p>
                <img src="client_get_started_suspend_error_fix.png" alt="Make main suspend" width="706"/>
            </step>
            <step>
                <p>
                    Finally, add <code>println</code> to print a <a href="response.md" anchor="status">status code</a> returned by a server.
                    Note that you also need to release resources holding by a client using the <code>close</code> method.
                    The <path>Main.kt</path> file should look in the following way:
                </p>
                <code style="block"
                      lang="kotlin"
                      src="snippets/tutorial-client-get-started/src/main/kotlin/Main.kt"/>
                <p>
                    In the next section, we'll run our program and make a request.
                </p>
            </step>
        </procedure>
    </chapter>


    <chapter title="Run a program and make a request" id="make-request">
        <p>
            Now we are ready to run our program a make a request.
        </p>
        <procedure hide-from-structure="true">
            <step>
                <p>
                    Click the gutter icon next to the <code>main</code> function and choose <control>Run 'MainKt'</control>.
                </p>
                <img src="client_get_started_run_main.png" alt="Run app" width="706"/>
            </step>
            <step>
                <p>
                    Wait until Intellij IDEA runs the application.
                    A server should respond with the <code>200 OK</code> (hopefully!) message.
                </p>
                <img src="client_get_started_run_output.png" alt="Server response" width="706"/>
            </step>
        </procedure>
    </chapter>
</topic>