|
| 1 | +# Домашно 3 |
| 2 | + |
| 3 | +`Краен срок: 18.01.2025, 23:59` |
| 4 | + |
| 5 | +С последната задача в курса ни надникваме в необятния свят на Интернет и уеб-базираните услуги, като ще упражним познанията ни за HTTP, REST и JSON. |
| 6 | + |
| 7 | +За разлика от предните задачи, този път няма да има автоматични референтни тестове, готови интерфейси, които да имплементирате или фиксирана от нас структура на проекта - имате цялата свобода, що се отнася до дизайна, имплементацията и тестването. |
| 8 | + |
| 9 | +## **News Feed** :newspaper: |
| 10 | + |
| 11 | +Ще създадем **библиотека** (по-точно Java *клиент* за REST API), която предоставя възможност за търсене на актуални новини по различни критерии. |
| 12 | + |
| 13 | +[REST API](https://newsapi.org/)-то, което ще използваме за намиране на новини, е публично, има безплатен план и използва автентикация с API Key, който може да вземем след [регистрация](https://newsapi.org/register). |
| 14 | + |
| 15 | +Необходимият ни endpoint e `/v2/top-headlines`, документиран [тук](https://newsapi.org/docs/endpoints/top-headlines). |
| 16 | + |
| 17 | +Безплатният план на API-то има своите лимити - можем да правим **до 100 заявки на ден**, заради което ще се наложи да обмислим и оптимизираме използването му, докато разработваме и тестваме. |
| 18 | + |
| 19 | +### Дизайн |
| 20 | + |
| 21 | +Както казва чичото на Спайдърмен: "With Great Power Comes Great Responsibility". |
| 22 | +Този път, вие определяте абстракциите, които ще използвате. Проектирайте API-то на вашата библиотека, така че да е максимално удобно и интуитивно за бъдещите му потребители. |
| 23 | +Ако желаете, използвайте възможността да приложите design patterns, въпреки че ще вземем темата на следващата (последна) лекция (задачата предразполага в това отношение) и съответно ще получите бонус. |
| 24 | +Освен удобство на API-то, помислете и за неговия performance и как може да го оптимизирате. Също, от гледна точка на security, помислете как да се подава и съхранява API Key-a, с който работи библиотеката ви - той ефективно е парола, та със сигурност не искате да е hardcoded в сорса. |
| 25 | + |
| 26 | +### Функционалност |
| 27 | + |
| 28 | +Критериите, по които можем да търсим новини, са: |
| 29 | + |
| 30 | +- ключови думи (задължителен параметър) |
| 31 | +- категория |
| 32 | +- държава |
| 33 | + |
| 34 | +Както може да видите в [документацията](https://newsapi.org/docs) на News API-то, то поддържа задължителни и опционални параметри - имплементацията ви също трябва да работи така - например, трябва да позволява търсене по ключови думи и категория, но не и само по държава. |
| 35 | + |
| 36 | +#### Странициране |
| 37 | + |
| 38 | +Когато едно API може да върне голям брой резултати, обикновено (от performance съображения) то не го прави на един път, а използва т.нар. *странициране* - връща резултатите на части (страници), като първо извличаме първа страница, после втора и т.н. За аналогия, представете си как като потребители през бразуър получаваме и обхождаме резултата от търсене в Google. |
| 39 | + |
| 40 | +:warning: **Важно:** Имайте предвид лимита от 100 request-a на ден, при имплементиране и тестване на тази част от задачата. |
| 41 | + |
| 42 | +#### Error handling |
| 43 | + |
| 44 | +При изпращане на request към сървъра, обработката му не винаги е успешна. Когато нещо се обърка, сървърът връща подходящ статус код и съобщение, които следва да обработвате. Моделирайте тази функционалност с помощта на custom checked exceptions. |
| 45 | +Различните грешки, които могат да се върнат, може да разгледате [тук](https://newsapi.org/docs/errors) |
| 46 | + |
| 47 | +### Тестване |
| 48 | + |
| 49 | +Сами отговаряте за цялостното тестване на решението си, ние пък ще оценяваме колко добре сте се справили с това. |
| 50 | +Целете се към висок code coverage, както и покрийте всички възможни сценарии, които вашата програма поддържа, включително такива, които могат да ви се сторят тривиални. |
| 51 | +За постигане на висок code coverage, може да се наложи да използвате Mockito. |
| 52 | + |
| 53 | +## **Предаване** |
| 54 | + |
| 55 | +За да предадете решението си, качете в съответния assignment в грейдъра `src` и `test` директориите на проекта (или техен общ `zip` архив). |
| 56 | + |
| 57 | +### **Оценяване** |
| 58 | + |
| 59 | +Решението може да ви донесе до 100 точки, като ще бъде оценявано за: |
| 60 | + |
| 61 | +* функционална пълнота и коректност, и за автоматични тестове с добър code coverage (50% от оценката). |
| 62 | + |
| 63 | + :warning: **Важно:** Решения без автоматични тестове няма да бъдат приемани и оценявани. |
| 64 | + |
| 65 | +* добър обектно-ориентиран дизайн, спазване на правилата за чист код и ефективност, в т.ч. подбиране на оптимални за задачата структури от данни и алгоритми (50% от оценката) |
| 66 | +* подходящото използване на design patterns може да ви донесе бонус точки |
| 67 | + |
| 68 | +**Успех!** :four_leaf_clover: |
0 commit comments