Add HTTP, REST & JSON Lab assignment

12-http-rest/lab/README.md

@@ -0,0 +1,53 @@
+# HTTP, REST и JSON
+
+С последната задача в курса ни надникваме в необятния свят на Интернет и уеб-базираните услуги, като ще упражним познанията ни за HTTP, REST и JSON.
+
+За разлика от предните задачи, този път няма да има автоматични референтни тестове, готови интерфейси, които да имплементирате или фиксирана от нас структура на проекта - имате цялата свобода, що се отнася до дизайна, имплементацията и тестването.
+
+## **News Feed** :newspaper:
+
+Ще създадем **библиотека** (по-точно Java *клиент* за REST API), която предоставя възможност за търсене на актуални новини по различни критерии.
+
+[REST API](https://newsapi.org/)-то, което ще използваме за намиране на новини, е публично, има безплатен план и използва автентикация с API Key, който може да вземем след [регистрация](https://newsapi.org/register).
+
+Необходимият ни endpoint e `/v2/top-headlines`, документиран [тук](https://newsapi.org/docs/endpoints/top-headlines).
+
+Безплатният план на API-то има своите лимити - можем да правим **до 100 заявки на ден**, заради което ще се наложи да обмислим и оптимизираме използването му, докато разработваме и тестваме.
+
+### Дизайн
+
+Както казва чичото на Спайдърмен: "With Great Power Comes Great Responsibility". 
+Този път, вие определяте абстракциите, които ще използвате. Проектирайте API-то на вашата библиотека, така че да е максимално удобно и интуитивно за бъдещите му потребители.
+Ако желаете, използвайте възможността да приложите design patterns, въпреки че ще вземем темата на следващата (последна) лекция (задачата предразполага в това отношение) и съответно ще получите бонус.
+Освен удобство на API-то, помислете и за неговия performance и как може да го оптимизирате. Също, от гледна точка на security, помислете как да се подава и съхранява API Key-a, с който работи библиотеката ви - той ефективно е парола, та със сигурност не искате да е hardcoded в сорса.
+
+### Функционалност
+
+Критериите, по които можем да търсим новини, са:
+
+- ключови думи (задължителен параметър)
+- категория
+- държава
+
+Както може да видите в [документацията](https://newsapi.org/docs) на News API-то, то поддържа задължителни и опционални параметри - имплементацията ви също трябва да работи така - например, трябва да позволява търсене по ключови думи и категория, но не и само по държава.
+
+#### Странициране
+
+Когато едно API може да върне голям брой резултати, обикновено (от performance съображения) то не го прави на един път, а използва т.нар. *странициране* - връща резултатите на части (страници), като първо извличаме първа страница, после втора и т.н. За аналогия, представете си как като потребители през бразуър получаваме и обхождаме резултата от търсене в Google.
+
+:warning: **Важно:** Имайте предвид лимита от 100 request-a на ден, при имплементиране и тестване на тази част от задачата.
+
+#### Error handling
+
+При изпращане на request към сървъра, обработката му не винаги е успешна. Когато нещо се обърка, сървърът връща подходящ статус код и съобщение, които следва да обработвате. Моделирайте тази функционалност с помощта на custom checked exceptions.
+Различните грешки, които могат да се върнат, може да разгледате [тук](https://newsapi.org/docs/errors)
+
+### Тестване
+
+Сами отговаряте за цялостното тестване на решението си, ние пък ще оценяваме колко добре сте се справили с това.
+Целете се към висок code coverage, както и покрийте всички възможни сценарии, които вашата програма поддържа, включително такива, които могат да ви се сторят тривиални.
+За постигане на висок code coverage, може да се наложи да използвате Mockito.
+
+## **Предаване**
+
+За да предадете решението си, качете в съответния assignment в грейдъра `src` и `test` директориите на проекта (или техен общ `zip` архив).