2024-2025/Lab/Mod5/Lab12/12.1.2 Retrofit Basics - Kotlin.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "615b1339-6713-4e9a-ad2f-59ed4e17cb16",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "9b010dbf-aa03-46c6-a1c0-0dfc89818e1d",
   "metadata": {},
   "source": [
    "# Retrofit2 - Podstawy"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "657c9a0f-5206-489f-9a8e-d0d726862949",
   "metadata": {},
   "source": [
    "W tej aplikacji przyjrzymy się zastosowaniu biblioteki **Retrofit** w aplikacji."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f50d99d5-c731-4a31-9667-4e1032dd1491",
   "metadata": {},
   "source": [
    "<img src=\"https://media2.giphy.com/media/v1.Y2lkPTc5MGI3NjExOGZjMHAzcnAwNHNmdzB5cHk3ZDQxYjVtMnZ4YmhsenFzd2RrN2NraSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/XqvcguuQ9qUzhJgLnQ/giphy.gif\" width=\"200\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c2afafa3-02ce-40bb-a1f6-74618091b160",
   "metadata": {},
   "source": [
    "`Retrofit` to popularna biblioteka do tworzenia interfejsów API w aplikacjach. Jest ona często używana do wykonywania zapytań HTTP do zdalnych serwerów i przetwarzania odpowiedzi. Jej prosty interfejs i możliwość dostosowania do różnych potrzeb sprawiają, że jest bardzo użyteczna przy tworzeniu aplikacji mobilnych, które wymagają integracji z serwerami internetowymi.\n",
    "\n",
    "- Współpracuje z biblioteką `OkHttp`: `Retrofit` bazuje na bibliotece `OkHttp` do zarządzania połączeniami HTTP. Dzięki temu możesz korzystać z funkcji takich jak zarządzanie ciasteczkami, buforowanie, logowanie żądań i odpowiedzi oraz wiele innych.\n",
    "- Definiowanie interfejsu API: Głównym celem `Retrofit` jest ułatwienie tworzenia interfejsów do zdalnych API. Tworzysz interfejs, a następnie określasz metody, które odpowiadają różnym zapytaniom HTTP. `Retrofit` **automatycznie** generuje implementację tego interfejsu, co pozwala na prostą i przejrzystą komunikację z serwerem.\n",
    "- Serializacja i deserializacja: `Retrofit` domyślnie obsługuje przekształcanie danych między formatem JSON a obiektami Javy/Kotlin. Możesz dostosować sposób serializacji i deserializacji, korzystając z różnych konwerterów (np. Gson, Moshi), lub też możesz użyć niestandardowych rozwiązań.\n",
    "- Obsługa różnych typów zapytań HTTP: `Retrofit` obsługuje różne typy zapytań HTTP, takie jak `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, itp. Możesz określić ścieżkę, parametry, nagłówki i ciało żądania w prosty i czytelny sposób.\n",
    "- Obsługa wielu endpointów: W jednej aplikacji możesz używać wielu różnych interfejsów API, co ułatwia integrację z różnymi serwerami i usługami.\n",
    "- Obsługa błędów: Retrofit umożliwia definiowanie obsługi błędów, co pozwala na reagowanie na różne sytuacje podczas komunikacji z serwerem. Możesz określić, jakie działania podjąć w przypadku błędnej odpowiedzi HTTP lub problemów z połączeniem.\n",
    "- Kotlin Coroutines: `Retrofit` jest często używany w połączeniu z Kotlin Coroutines, co umożliwia asynchroniczną obsługę zapytań HTTP i reaktywne programowanie.\n",
    "- `Retrofit` obsługuje różne mechanizmy autentykacji, takie jak tokeny `OAuth`, autoryzacja `Basic`, czy też niestandardowe rozwiązania."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b4cef8eb-953a-432c-bbb1-3675db508028",
   "metadata": {},
   "source": [
    "`Retrofit` oferuje wiele różnych konwerterów, które pozwalają na serializację (z przekształcaniem danych z formatu np. JSON na obiekty) i deserializację (z przekształcaniem obiektów na format np. JSON) danych w zależności od potrzeb. Kilka popularnych konwerterów:\n",
    "- `GsonConverter`: To jeden z najczęściej używanych konwerterów. Wykorzystuje bibliotekę `Gson` do przekształcania danych JSON na obiekty Javy/Kotlin i vice versa. Wymaga dodatkowej zależności Gson w projekcie.\n",
    "```kotlin\n",
    "implementation 'com.squareup.retrofit2:converter-gson:latest_version'\n",
    "```\n",
    "- `MoshiConverter`: To inny popularny konwerter, który wykorzystuje bibliotekę `Moshi` do przekształcania danych JSON. Moshi jest lekką i wydajną biblioteką, która jest często wybierana przez deweloperów.\n",
    "```kotlin\n",
    "implementation 'com.squareup.retrofit2:converter-moshi:latest_version'\n",
    "```\n",
    "- `JacksonConverter`: Ten konwerter korzysta z biblioteki `Jackson` do obsługi serializacji i deserializacji danych JSON.\n",
    "```kotlin\n",
    "implementation 'com.squareup.retrofit2:converter-jackson:latest_version'\n",
    "```\n",
    "- `ScalarsConverter`: Pozwala na przekształcanie prostych typów danych, takich jak `String`, `Boolean` czy `Integer`, bezpośrednio z odpowiedzi HTTP.\n",
    "```kotlin\n",
    "implementation 'com.squareup.retrofit2:converter-scalars:latest_version'\n",
    "```\n",
    "- `SimpleXMLConverter`: Jeśli API korzysta z formatu XML, ten konwerter pozwala na przekształcanie danych XML na obiekty Javy/Kotlin.\n",
    "```kotlin\n",
    "implementation 'com.squareup.retrofit2:converter-simplexml:latest_version'\n",
    "```\n",
    "- `protobufConverter`: Ten konwerter jest przeznaczony do obsługi danych w formacie `Protocol Buffers` (`protobuf`).\n",
    "```kotlin\n",
    "implementation 'com.squareup.retrofit2:converter-protobuf:latest_version'\n",
    "```\n",
    "- `WireConverter`: `Wire` to inna biblioteka do obsługi formatu `Protocol Buffers`.\n",
    "```kotlin\n",
    "implementation 'com.squareup.retrofit2:converter-wire:latest_version'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "695d5996-0178-4e4d-8812-dbc9d3c9a957",
   "metadata": {},
   "source": [
    "W tym przykładzie wykorzystamy [**JSONPlaceholder**](https://jsonplaceholder.typicode.com/), który jest API przeznaczonym do testowania. Mamy dostępnych kilka **endpointów**\n",
    "- posts\n",
    "- comments\n",
    "- albums\n",
    "- photos\n",
    "- todos\n",
    "- users\n",
    "\n",
    "W tym przykładzie wybierzemy pierwszy (posts), rozpoczniemy komunikację z tym serwerem oraz asynchronicznie wykonamy operację `GET` - czyli pobierzemy wszystkie posty. Posty znajdziemy w formacie `JSON` - jest to format służący komunikacji pomiędzy naszą aplikacją a serwerem. Na serwerze znajduje się w chwili pisania 100 postów, struktura pojedynczego postu wygląda następująco"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "757a62d0-78c0-472f-8741-593c0804e217",
   "metadata": {},
   "outputs": [],
   "source": [
    "{\n",
    "    \"userId\": 1,\n",
    "    \"id\": 1,\n",
    "    \"title\": \"sunt aut ...\",\n",
    "    \"body\": \"quia et ...\"\n",
    "},"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff697d75-73eb-48de-bd69-3967e8d2f4ae",
   "metadata": {},
   "source": [
    "Nasza aplikacja wymaga dostępu do internetu, aby go uzyskać musimy dodać deklarację uprawnienia w pliku konfiguracyjnym aplikacji, który nazywa się `AndroidManifest.xml`. To uprawnienie informuje system operacyjny Android, że aplikacja potrzebuje dostępu do internetu."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e7d36068-d3aa-481a-b079-85df30382f79",
   "metadata": {},
   "outputs": [],
   "source": [
    "<uses-permission android:name=\"android.permission.INTERNET\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f1854c4b-2f74-44bb-8b87-c1fd3523043c",
   "metadata": {},
   "source": [
    "Następnie dodajmy wymagane zależności do projektu.\n",
    "\n",
    "```kotlin\n",
    "    implementation (libs.retrofit)\n",
    "    implementation (libs.gson)\n",
    "    implementation (libs.converter.gson)\n",
    "\n",
    "    // ViewModel\n",
    "    implementation (libs.androidx.lifecycle.viewmodel.ktx)\n",
    "    //Fragment\n",
    "    implementation (libs.androidx.fragment.ktx)\n",
    "```\n",
    "\n",
    "```kotlin\n",
    "[versions]\n",
    "agp = \"8.5.2\"\n",
    "converterGson = \"2.11.0\"\n",
    "fragmentKtx = \"1.8.2\"\n",
    "gson = \"2.10.1\"\n",
    "kotlin = \"1.9.0\"\n",
    "coreKtx = \"1.13.1\"\n",
    "junit = \"4.13.2\"\n",
    "junitVersion = \"1.2.1\"\n",
    "espressoCore = \"3.6.1\"\n",
    "appcompat = \"1.7.0\"\n",
    "lifecycleViewmodelKtx = \"2.8.4\"\n",
    "material = \"1.12.0\"\n",
    "activity = \"1.9.1\"\n",
    "constraintlayout = \"2.1.4\"\n",
    "\n",
    "[libraries]\n",
    "androidx-core-ktx = { group = \"androidx.core\", name = \"core-ktx\", version.ref = \"coreKtx\" }\n",
    "androidx-fragment-ktx = { module = \"androidx.fragment:fragment-ktx\", version.ref = \"fragmentKtx\" }\n",
    "androidx-lifecycle-viewmodel-ktx = { module = \"androidx.lifecycle:lifecycle-viewmodel-ktx\", version.ref = \"lifecycleViewmodelKtx\" }\n",
    "converter-gson = { module = \"com.squareup.retrofit2:converter-gson\", version.ref = \"converterGson\" }\n",
    "gson = { module = \"com.google.code.gson:gson\", version.ref = \"gson\" }\n",
    "junit = { group = \"junit\", name = \"junit\", version.ref = \"junit\" }\n",
    "androidx-junit = { group = \"androidx.test.ext\", name = \"junit\", version.ref = \"junitVersion\" }\n",
    "androidx-espresso-core = { group = \"androidx.test.espresso\", name = \"espresso-core\", version.ref = \"espressoCore\" }\n",
    "androidx-appcompat = { group = \"androidx.appcompat\", name = \"appcompat\", version.ref = \"appcompat\" }\n",
    "material = { group = \"com.google.android.material\", name = \"material\", version.ref = \"material\" }\n",
    "androidx-activity = { group = \"androidx.activity\", name = \"activity\", version.ref = \"activity\" }\n",
    "androidx-constraintlayout = { group = \"androidx.constraintlayout\", name = \"constraintlayout\", version.ref = \"constraintlayout\" }\n",
    "retrofit = { module = \"com.squareup.retrofit2:retrofit\", version.ref = \"converterGson\" }\n",
    "\n",
    "[plugins]\n",
    "android-application = { id = \"com.android.application\", version.ref = \"agp\" }\n",
    "jetbrains-kotlin-android = { id = \"org.jetbrains.kotlin.android\", version.ref = \"kotlin\" }\n",
    "\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a370be5f-3ade-4c91-876c-080103a0afc3",
   "metadata": {},
   "source": [
    "W pierwszym kroku musimy stworzyć nasz model danych odpowiadający strukturze obecnej na serwerze."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1b73ecc5-76ab-48dd-bf06-cd06b880ab60",
   "metadata": {},
   "outputs": [],
   "source": [
    "data class Post (\n",
    "    val userId: Int,\n",
    "    val id: Int,\n",
    "    val title: String,\n",
    "\n",
    "    @SerializedName(\"body\")\n",
    "    val content: String\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "188606e5-4c69-4c1b-8c0a-f61d64c6d461",
   "metadata": {},
   "source": [
    "Nowym elementem jest zastosowana adnotacja `@SerializedName`. Jest to adnotacja dostarczana przez bibliotekę `Gson`. Informuje serializator/deserializator JSON o tym, że pole `body` w obiekcie JSON powinno być mapowane na to pole `content` w obiekcie Kotlin."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f1b17fde-2d7e-4bdc-9098-908c934c4c6e",
   "metadata": {},
   "source": [
    "W kolejnym kroku dodajmy interfejs `PlaceholderApi`, służy on do definiowania zestawu metod, które będą używane do wykonywania zapytań HTTP do zdalnego API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "26d8d40f-8b86-4581-8af2-ec9689f94103",
   "metadata": {},
   "outputs": [],
   "source": [
    "interface PlaceholderApi {\n",
    "    @GET(\"posts\")\n",
    "    suspend fun posts(): List<Post>\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d8c58102-e8ef-4ba3-9234-cbc360e8c4dd",
   "metadata": {},
   "source": [
    "- `@GET(\"posts\")`: Adnotacja `@GET` używana jest w `Retrofit` do oznaczania, że ta metoda interfejsu będzie używana do wykonywania żądania HTTP typu GET. Argument `\"posts\"` wskazuje ścieżkę URL, do której zostanie wysłane to żądanie. Jeśli na przykład podajesz bazowy adres URL jako `https://example.com/api/`, to ta metoda będzie próbować wykonać zapytanie pod adres `https://example.com/api/posts`.\n",
    "- `suspend fun posts(): List<Post>`: Oczekujemy, że po wykonaniu zapytania GET na ścieżce `\"posts\"` otrzymamy listę obiektów typu `Post`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0589055d-dbbd-4b59-92e2-a8d46e971c5f",
   "metadata": {},
   "source": [
    "Musimy stworzyć instancję `Retrofit`, którą będziemy się posługiwać w aplikacji - będzie to singleton."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bf996a3a-860f-439f-addf-060f9871737c",
   "metadata": {},
   "outputs": [],
   "source": [
    "object RetrofitInstance {\n",
    "    val api: PlaceholderApi by lazy {\n",
    "        Retrofit.Builder()\n",
    "            .baseUrl(\"https://jsonplaceholder.typicode.com/\")\n",
    "            .addConverterFactory(GsonConverterFactory.create())\n",
    "            .build()\n",
    "            .create(PlaceholderApi::class.java)\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "88c0d4e5-c8e5-4b30-9b2a-07b00edcbfce",
   "metadata": {},
   "source": [
    "- `val api: PlaceholderApi by lazy { ... }`: Jest to pole `api`, które jest inicjowane leniwie (`lazy`). Oznacza to, że instancja obiektu o typie `PlaceholderApi` zostanie utworzona dopiero w momencie pierwszego dostępu do tego pola.\n",
    "- `Retrofit.Builder()`: Tworzy instancję budowniczego obiektu `Retrofit`, który pozwoli na skonfigurowanie i dostosowanie zachowania biblioteki `Retrofit`.\n",
    "- `.baseUrl(\"https://jsonplaceholder.typicode.com/\")`: Metoda `baseUrl` ustawia bazowy adres URL, który będzie używany do wszystkich zapytań HTTP. W tym przypadku, bazowy adres URL to `\"https://jsonplaceholder.typicode.com/\"`.\n",
    "- `.addConverterFactory(GsonConverterFactory.create())`: Metoda `addConverterFactory` dodaje konwerter do obsługi serializacji i deserializacji danych w formacie JSON. Używamy `GsonConverterFactory`, który korzysta z biblioteki `Gson` do przekształcania danych JSON na obiekty i vice versa.\n",
    "- `.build()`: Ta metoda kończy konfigurację obiektu `Retrofit` i tworzy finalną instancję.\n",
    "- `.create(PlaceholderApi::class.java)`: Metoda `create` tworzy implementację obiektu o typie interfejsu `PlaceholderApi`, która jest używana do wykonywania żądań HTTP do zdalnego API."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ea6e93c5-cb88-4a2c-a6e4-4701d6051569",
   "metadata": {},
   "source": [
    "Dodajmy ównież repozytorium."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "319463ed-cd63-42e3-a0e6-3bcf6fc897b3",
   "metadata": {},
   "outputs": [],
   "source": [
    "class PostRepository {\n",
    "    private val api = RetrofitInstance.api\n",
    "\n",
    "    suspend fun getPosts(): List<Post>{\n",
    "        return api.posts()\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c22ac303-dbff-4bb5-8cb5-8d58446827f4",
   "metadata": {},
   "source": [
    "Następnie dodajmy viewmodel."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1608011a-30c1-41d2-8634-45d32dd681bb",
   "metadata": {},
   "outputs": [],
   "source": [
    "class PostViewModel : ViewModel() {\n",
    "    private val repository = PostRepository()\n",
    "    private val _posts = MutableStateFlow(emptyList<Post>())\n",
    "    val posts: StateFlow<List<Post>> = _posts\n",
    "\n",
    "    init {\n",
    "        getPosts()\n",
    "    }\n",
    "\n",
    "    private fun getPosts() {\n",
    "        viewModelScope.launch {\n",
    "            _posts.value = repository.getPosts()\n",
    "        }\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c291d94a-ecc3-4e67-a811-3e257686d8f5",
   "metadata": {},
   "source": [
    "Ostatnim elementem jest dodanie klas obsługujących `RecyclerView` oraz fragment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "08169d28-c592-4829-bad2-5c2e87637dcb",
   "metadata": {},
   "outputs": [],
   "source": [
    "class PostViewHolder(private val binding: RvItemBinding) : RecyclerView.ViewHolder(binding.root) {\n",
    "    fun bind(item: Post) {\n",
    "        binding.apply {\n",
    "            title.text = item.title\n",
    "            content.text = item.content\n",
    "            userId.text = item.userId.toString()\n",
    "        }\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0eb048e7-c456-4e13-a4c4-978d3fee39d1",
   "metadata": {},
   "outputs": [],
   "source": [
    "class PostComparator : DiffUtil.ItemCallback<Post>() {\n",
    "    override fun areItemsTheSame(oldItem: Post, newItem: Post): Boolean {\n",
    "        return oldItem === newItem\n",
    "    }\n",
    "\n",
    "    override fun areContentsTheSame(oldItem: Post, newItem: Post): Boolean {\n",
    "        return oldItem == newItem\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "92156466-10b0-494d-98e6-f1262535a640",
   "metadata": {},
   "outputs": [],
   "source": [
    "class PostAdapter(userComparator: PostComparator) : ListAdapter<Post, PostViewHolder>(userComparator) {\n",
    "    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): PostViewHolder {\n",
    "        return PostViewHolder(\n",
    "            RvItemBinding.inflate(\n",
    "                LayoutInflater.from(parent.context), parent, false\n",
    "            )\n",
    "        )\n",
    "    }\n",
    "\n",
    "    override fun onBindViewHolder(holder: PostViewHolder, position: Int) {\n",
    "        val item = getItem(position)\n",
    "        holder.bind(item)\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "24fa6ec8-4d3d-4dc4-a344-0ccbc01a67da",
   "metadata": {},
   "outputs": [],
   "source": [
    "class PostFragment : Fragment() {\n",
    "\n",
    "    private lateinit var binding: FragmentPostBinding\n",
    "\n",
    "    private val viewModel: PostViewModel by viewModels()\n",
    "\n",
    "    override fun onCreateView(\n",
    "        inflater: LayoutInflater, container: ViewGroup?,\n",
    "        savedInstanceState: Bundle?\n",
    "    ): View {\n",
    "        binding = FragmentPostBinding.inflate(inflater)\n",
    "\n",
    "        val userAdapter = PostAdapter(PostComparator())\n",
    "        viewLifecycleOwner.lifecycleScope.launch {\n",
    "            viewModel.posts.collectLatest { posts ->\n",
    "                userAdapter.submitList(posts)\n",
    "            }\n",
    "        }\n",
    "\n",
    "        binding.recycler.apply{\n",
    "            adapter = userAdapter\n",
    "            layoutManager = LinearLayoutManager(requireContext())\n",
    "        }\n",
    "\n",
    "        return binding.root\n",
    "    }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0eb11642-5b8d-4bac-8e8c-f038cbec26f3",
   "metadata": {},
   "source": [
    "Możemy przetestować aplikację."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "781634d8-0ed0-432f-9525-bcaddccc4fc8",
   "metadata": {},
   "source": [
    "<img src=\"https://media2.giphy.com/media/v1.Y2lkPTc5MGI3NjExOGZjMHAzcnAwNHNmdzB5cHk3ZDQxYjVtMnZ4YmhsenFzd2RrN2NraSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/XqvcguuQ9qUzhJgLnQ/giphy.gif\" width=\"200\" />"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Kotlin",
   "language": "kotlin",
   "name": "kotlin"
  },
  "language_info": {
   "codemirror_mode": "text/x-kotlin",
   "file_extension": ".kt",
   "mimetype": "text/x-kotlin",
   "name": "kotlin",
   "nbconvert_exporter": "",
   "pygments_lexer": "kotlin",
   "version": "1.8.0-RC"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}