УВОД

Целта на курсовия проект е да се разработи RESTful API за запазване на час при лекар. API-то трябва да извършва следните задачи:

Да връща данни за всички налични в системата лекари.
Да има възможност за търсене на лекар по въведени критерии.
Да връща данни за свободен ден и час на избран лекар.
Да извършва запис на запазения час в системата.
Да обновява информация за запазен час.
Да анулира запазен час.

За целта е разработена база данни, която да съхранява следните данни:

Информация за лекарите
Работно време на лекарите
Специализации на лекарите
Почивни дни на лекарите
Данни за запазените часове
Данни за пациента
Информация за причини на посещения при лекар

За програмната реализация е използван MS SQL Server за базата данни. За реализирането на API-то е използван езикът за програмиране C#.

Използваните развойни среди за разработка са SQL Server Management Studio и Microsoft Visual Studio 2017.

Разработеното API може да бъде внедрено в системата за здравеопазване като би предлагало лесно и удобно запазване на часове при различни лекари.

API-то има възможни различни направления за развитие, които могат да бъдат разработени, в зависимост от нуждите.

Документация в POSTMAN

Документация в POSTMAN може да бъде видяна тук.

Описание на Методи

Методите се изпълняват чрез удостоверяване с API KEY.

key	APIkey
value	Your key here

2.1. GET List All Doctors Paginated

Методът връща данни за всички налични лекари в системата

2.1.1. Параметри

ПАРАМЕТЪР	ТИП ДАННИ	ОПИСАНИЕ	ЗАБЕЛЕЖКИ
PageNum	Integer	Номер на страницата, която желаете да бъде върната. (Стойност по подразбиране е 1)	Допустими стойности са PageNum > 0
PageSize	Integer	Колко записа да бъдат върнати за конкретната страница. (Стойност по подразбиране е 10)	Допустими стойности са PageSize > 0
type	String	Тип на върнатия резултат.	Възможни параметри са json или xml.

2.1.2. Примери

http://localhost:{{PortNumber}}/api/doctors/PageNum/1/PageSize/10?type=json

[

{

"id": 174,

"fnm": "Дафина",

"snm": "Колева",

"sal_nme": "Д-р",

"spec_nme": "Акушер-гинеколог",

"bio": "Additional Information.",

"img_url": "/Images/ProfilePictures/Default/doctor-default.png",

"max_bok_day": 60,

"city_nme": "Бургас",

"eml": "pn@abv.bg",

"tel": "0884719728",

"ful_nme": "Дафина Колева",

"first_avl_day": "2020-12-06T00:00:00"

{

"id": 149,

"fnm": "Стефания",

"snm": "Петкова",

"sal_nme": "Д-р",

"spec_nme": "Алерголог",

"bio": "Additional Information.",

"img_url": "/Images/ProfilePictures/Stefani.jpg",

"max_bok_day": 60,

"city_nme": "Кърджали",

"eml": "mt@abv.bg",

"tel": "0887867421",

"ful_nme": "Стефания Петкова",

"first_avl_day": "2020-12-01T00:00:00"

}

]

2.1.3. Описание на Response

RESPONSE KEY	ОПИСАНИЕ
id	Id на лекаря
fnm	Име на лекаря
snm	Фамилия
sal_nme	Титла
spec_nme	Наименование на специализацията му
bio	Биография на лекаря
img_url	Снимка на лекаря
max_bok_day	Максимум дни напред, в които може да се запазва час при конкретния лекар
city_nme	Град, в който лекаря работи
eml	e-mail за контакт с лекаря
tel	Телефон за контакт с лекаря
ful_nme	Пълно име на лекаря
first_avl_day	Първа свободна дата за запазване на час

2.2. GET Search Doctors

Търсене на лекар по зададени критерии.
Може да се търси по един или повече от един параметъра.

2.2.1. Параметри

ПАРАМЕТЪР	ТИП ДАННИ	ОПИСАНИЕ	ЗАБЕЛЕЖКИ
DocId	Integer	Id на лекаря	Допустими стойности са DocID > 0
FullName	String	Име на лекаря	Може да бъде първо име, цяло име, или част от името.
CityId	Integer	ID на града, в който работи	Трябва да е по-голямо от 0.
SpecId	Integer	ID на специалността на лекаря	Трябва да е по-голямо от 0.
Eml	String	e-mail на лекаря	Трябва да е в коректен mail формат.
Tel	Integer	Телефон на лекаря	Трябва да съдържа само цифри.
type	String	Тип на върнатия резултат.	Възможни параметри са json или xml.

2.2.2. Примери

http://localhost:{port_number}/api/doctors?DocId=3&type=json

[

{

"id": 3,

"fnm": "Петър",

"snm": "Стоянов",

"sal_nme": "Д-р",

"spec_nme": "Кардиолог",

"bio": "Кратка информация за Петър Стоянов",

"img_url": "/Images/ProfilePictures/Default/doctor-default.png",

"max_bok_day": 60,

"city_nme": "София",

"eml": "ps@gmail.com",

"tel": "0892222222",

"ful_nme": "Петър Стоянов",

"first_avl_day": "2020-12-05T00:00:00"

}

]

2.2.3. Описание на Response

RESPONSE KEY	ОПИСАНИЕ
id	Id на лекаря
fnm	Име на лекаря
snm	Фамилия
sal_nme	Титла
spec_nme	Наименование на специализацията му
bio	Биография на лекаря
img_url	Снимка на лекаря
max_bok_day	Максимум дни напред, в които може да се запазва час при конкретния лекар
city_nme	Град, в който лекаря работи
eml	e-mail за контакт с лекаря
tel	Телефон за контакт с лекаря
ful_nme	Пълно име на лекаря
first_avl_day	Първа свободна дата за запазване на час

2.3. GET Doctor Available Days and Hours

Връща данни за дните, в които лекарят има свободни часове.
Може да се използва за проверка на конкретна дата – в този случай подайте на NumDays = 0.
Когато NumDays > 0 то ще връща N дни след входната дата Date и информация за свободните часове.

2.3.1. Параметри

ПАРАМЕТЪР	ТИП ДАННИ	ОПИСАНИЕ	ЗАБЕЛЕЖКИ
DocId	Integer	Id на лекаря	Трябва да е по-голямо от 0.
Date	String	Начална дата, от която да започне проверката	Трябва да е форматирана по следния начин: yyyy-MM-dd
NumDays	Integer	Брой дни	Определя колко дни напред от календара спрямо днешна дата, да се върнат. Ако искате да се провери дали конкретна дата е свободна и наличните й часове, то подайте на този параметър 0. Параметърът трябва да е по-голям или равен на 0.
type	String	Тип на върнатия резултат.	Възможни параметри са json или xml.

2.3.2. Примери

http://localhost:{{PortNumber}}/api/doctors/docId/3/date/2020-12-05/NumDays/3/available-days?type=json

[

{

"_date": "2020-12-01T00:00:00",

"is_avl": 0,

"avl_time": "00:00",

"weekday_name": "Tuesday"

{

"_date": "2020-12-02T00:00:00",

"is_avl": 0,

"avl_time": "00:00",

"weekday_name": "Wednesday"

{

"_date": "2020-12-03T00:00:00",

"is_avl": 0,

"avl_time": "00:00",

"weekday_name": "Thursday"

}

]

2.3.3. Описание на Response

RESPONSE KEY	ОПИСАНИЕ
date	Дата
is_avl	Флаг дали е свободен денят – 1 за свободен; 0 – няма свободни часове;
avl_time	Час, който може да бъде запазен. (Когато is_avl = 0, то този час по подразбиране ще е равен на 00:00)
weekday_name	Наименование на деня

2.4. GET Get Available Reasons

Връща данни за всички налични в системата причини за запазване на час.

2.4.1. Параметри

ПАРАМЕТЪР	ТИП ДАННИ	ОПИСАНИЕ	ЗАБЕЛЕЖКИ
type	String	Тип на върнатия резултат.	Възможни параметри са json или xml.

2.4.2. Примери

http://localhost:{{PortNumber}}/api/bookings/reasons?type=json

[

{

"id": 1,

"nme": "Първичен преглед"

{

"id": 2,

"nme": "Вторичен преглед"

{

"id": 3,

"nme": "Профилактичен преглед"

{

"id": 4,

"nme": "Детска консултация"

}

]

2.4.3. Описание на Response

RESPONSE KEY	ОПИСАНИЕ
id	Id на причина за запазване на час
nme	Наименование на причината

2.5. POST Create Booking

Метод за създаване на запис в базата данни, който пази информация за запазения час.
Методът извършва следните проверки:
- Не може да се запазва час на предишна дата.
- Не може да се запазва час в ден, който е по-голям от днешния + max_bok_days. Т.е. ако max_bok_days = 30 и днешна дата е 01.12.2020г., то 30.12.2020г. е последният ден, в който може да се запази час. Този параметър се настройва динамично за всеки лекар.
- Не може да се запазва час в ден, в който лекарят не работи – в случай, че бъде подадена такава дата като входен параметър.
- Не може да се запазва час във време, в което лекарят не е на смяна.
- Запазен час не може да се дублира.

2.5.1. Параметри

ПАРАМЕТЪР	ТИП ДАННИ	ОПИСАНИЕ	ЗАБЕЛЕЖКИ
Fname	String	Име на пациент.	Дължина – 50 символа. (позволени са само букви)
Lname	String	Фамилия на пациент	Дължина – 50 символа. (позволени са само букви)
Tel	String	Телефон на пациент	Дължина – 10 цифри (позволени са само цифр)
Eml	String	e-mail на пациент	Дължина – 75 символа.
AddInfo	String	Допълнителна информация/оплаквания.	Дължина – 500 символа.
IsFirstTime	Bool	Флаг – за първи път ли се посещава лекаря	1 – посещава за ПЪРВИ ПЪТ 0 – посещавал е и ПРЕДИ
Gender	String	Пол на пациента	M - мъж, FM - жена, DK - не желая да посоча.
ReasonId	Integer	Id на причина за посещение на пациента	Може да се вземе от 2.4. Get Available Reasons (Трябва да е > 0)
DocId	Integer	Id на доктора	Трябва да е > 0.
BokDate	Date	Дата, в която пациентът иска да бъде запазен часът.	Трябва да е във формат yyyy-MM-dd. Трябва да е по-голяма от днешна дата.
BokTime	Time	Час, който да бъде запазен.	Трябва да е във формат hh:mm, като hh да е между 0 и 23 и mm да е между 0 и 59.
Type	String	Тип на върнатия резултат.	Възможни параметри са json или xml.

2.5.2. Примери

BODY - Пример

{

"Fname" : "API",

"Lname" : "Test",

"Tel" : "0881145781",

"Eml" : "test@abv.bg",

"AddInfo" : "Testing the API for 3 time. And commas, should work now. (I think so)",

"IsFirstTime" : "1",

"Gender" : "dk",

"ReasonId" : "1",

"DocId" : "3",

"BokDate" : "2020-11-21",

"BokTime" : "12:00"

http://localhost:{port_number}/api/bookings?type=json

"Your booking is created successfully. Booking Reference: 20201205120018"

2.5.3. Описание на Response

При успех
- Връща се съобщение с успех и референция към запазения час, която е уникална.
- Status code = 200
При неуспех
- Връща се съобщение с грешката.

2.6. PUT Update Booking

Обновява данни за запазения час.
Всички параметри са същите като при Create Booking метода. Единствената разлика е, че тук трябва да бъде подадена референция, която искате да редактирате.

2.6.1. Параметри

ПАРАМЕТЪР	ТИП ДАННИ	ОПИСАНИЕ	ЗАБЕЛЕЖКИ
Reference	String	Референция към запазения час, която се генерира при запазване на час.	Референцията се връща при успешно изпълнение на Create Booking – 2.5.
Fname	String	Име на пациент.	Дължина – 50 символа. (позволени са само букви)
Lname	String	Фамилия на пациент	Дължина – 50 символа. (позволени са само букви)
Tel	String	Телефон на пациент	Дължина – 10 цифри (позволени са само цифр)
Eml	String	e-mail на пациент	Дължина – 75 символа.
AddInfo	String	Допълнителна информация/оплаквания.	Дължина – 500 символа.
IsFirstTime	Bool	Флаг – за първи път ли се посещава лекаря	1 – посещава за ПЪРВИ ПЪТ 0 – посещавал е и ПРЕДИ
Gender	String	Пол на пациента	M - мъж, FM - жена, DK - не желая да посоча.
ReasonId	Integer	Id на причина за посещение на пациента	Може да се вземе от 2.4. Get Available Reasons (Трябва да е > 0)
DocId	Integer	Id на доктора	Трябва да е > 0.
BokDate	Date	Дата, в която пациентът иска да бъде запазен часът.	Трябва да е във формат yyyy-MM-dd. Трябва да е по-голяма от днешна дата.
BokTime	Time	Час, който да бъде запазен.	Трябва да е във формат hh:mm, като hh да е между 0 и 23 и mm да е между 0 и 59.
Type	String	Тип на върнатия резултат.	Възможни параметри са json или xml.

2.6.2. Примери

BODY - Пример

{ "Reference" : "20201205120018", "Fname" : "Proba", "Lname" : "Test", "Tel" : "0881111111", "Eml" : "test5@abv.bg", "AddInfo" : "Testing the API for 4 time. And commas, should work now. (I think so)", "IsFirstTime" : "1", "Gender" : "m", "ReasonId" : "2", "DocId" : "3", "BokDate" : "2020-11-21", "BokTime" : "12:00" }

http://localhost:{port_number}/api/bookings?type=json

{

"APIerrorCode": "0",

"Status": 200,

"Message": "Your booking has been edited successfully."

}

2.6.3. Описание на Response

RESPONSE KEY	ОПИСАНИЕ
APIerrorCode	Код на грешка от базата данни. 0 означава, че няма грешка.
Status	Статус
Message	Съобщение

2.7. DELETE Cancel Booking

Методът анулира запазен час.

2.7.1. Параметри

ПАРАМЕТЪР	ТИП ДАННИ	ОПИСАНИЕ	ЗАБЕЛЕЖКИ
Reference	String	Референция към запазения час, която се генерира при запазване на час.	Референцията се връща при успешно изпълнение на Create Booking – 2.5.
Type	String	Тип на върнатия резултат.	Възможни параметри са json или xml.

2.7.2. Примери

BODY - Пример

{ "20201205110019"}

http://localhost:{port_number}/api/bookings?type=json

{

"APIerrorCode": "0",

"Status": 200,

"Message": "Booking Canceled successfully."

}

2.7.3. Описание на Response

RESPONSE KEY	ОПИСАНИЕ
APIerrorCode	Код на грешка от базата данни. 0 означава, че няма грешка.
Status	Статус
Message	Съобщение

2.8. GET Booking Info

Връща данни за запазен час по референция.

2.8.1. Параметри

ПАРАМЕТЪР	ТИП ДАННИ	ОПИСАНИЕ	ЗАБЕЛЕЖКИ
Reference	String	Референция към запазения час, която се генерира при запазване на час.	Референцията се връща при успешно изпълнение на Create Booking – 2.5.
Type	String	Тип на върнатия резултат.	Възможни параметри са json или xml.

2.8.2. Примери

Пример

http://localhost:{{PortNumber}}/api/bookings/202012121130111?type=json

{

"Reference": "202012121130111",

"Fname": "APIto",

"Lname": "Test",

"Tel": "0881145781",

"Eml": "test12@abv.bg",

"AddInfo": "Testing the API for 3 time. And commas, should work now. (I think so)",

"IsFirstTime": false,

"Gender": "dk",

"ReasonId": 1,

"DocId": 3,

"BokDate": "12-Dec-20 12:00:00 AM",

"BokTime": "11:30:00"

}

2.8.3. Описание на Response

RESPONSE KEY	ОПИСАНИЕ
Reference	Уникална референция за запазения час
Fname	Име на пациента
Lname	Фамилия на пациента
Tel	Телефон на пациента
Eml	E-mail за контакт на пациента
AddInfo	Допълнителна информация за пациента
IsFirstTime	За първи път ли посещава лекаря
Gender	Пол на пациента
ReasonId	ID на причината за посещение на пациента
DocId	ID на лекаря, който пациента ще посещава
BokDate	Дата, в която пациентът е запазил час
BokTime	Час, който пациентът е запазил

2.9. Error Handling

За всички методи – при възникване на грешка се връща json със следния вид:

Error Response

{

"APIerrorCode": "0",

"Status": 200,

"Message": "Booking Canceled successfully."

}

Където всяко от полето означава:

RESPONSE KEY	ОПИСАНИЕ
APIerrorCode	Код на грешка от базата данни. 0 означава, че няма грешка.
Status	Статус
Message	Съобщение

Чрез запазване на APIerrorCode по-лесно може да бъде правена поддръжка от страна на разработчиците, тъй като всеки код на грешката е уникален и по него може да се открива бързо и лесно.

2.10. Кодове на грешки

2.10.1. В API

1007	AddInfo Length must be less than 500 symbols.
1009	Date must be greater or equal to Today's date.
1016	No doctors to show.
1010	The parameter must not be empty.
1011	The parameter must be greater than zero.
1012	Invalid input.
1003	Parameter must contain only chars and numbers.
1002	Parameter must contain chars only.
1005	Parameter must be in correct date format.
1001	Parameter must be in correct e-mail format.
1004	Parameter must contain numbers only.
1006	Parameter must be in correct time format.
1000	There is no error.
1013	There are no reasons to show.
1014	PageNumber must be greater than or equal to zero.
1015	PageSize must be greater than or equal to zero.
0	Success. OK.
1008	Telephone must be less than or equal to 10 digits.
1009	You need to provide your APIKey in order to access the API.

2.10.2. В базата данни

106	Gender must be m fm or dk.
107	There is no such reason ID.
108	Doctor with this id does not exist.
102	You cannot make a booking in previous date or hour.
103	You cannot make a booking in later than today + @p_max_bok_day day.
104	You cannot make a booking at this date because the doctor does not work at this day.
105	You cannot make a booking at this time because the doctor does not work at this hour.
101	You cannot book at this hour because there is already an existing booking.
203	There is no booking with this Reference.
201	This booking is already canceled.
202	You cannot cancel a booking which date or hour is in the past.
300	You are using APIKey that not exists on this system. Please check again your APIKey.
301	Your APIKey has expired at *date*. Please register a new one.