Рекомендации по использованию REST API

Question

Мы разрабатываем API REST, и мы разрешаем все четыре стандартных глагола. В случае POST/PUT клиенту API необходимо будет изменять значения для определенных полей. Возьмем пример псевдо:

class Employee { 
    long Id; 
    long DepartmentId; // should i expose this? 
    string Department; // or should i expose this? 
} 

• Потребительная дело здесь в том, что клиент будет POST нового сотрудника и заполнить все поля.
• Существует таблица отделов в нашей базе данных за API
• Клиент должен будет получить список допустимых отделов отправить
• клиент может сделать вызов API, чтобы получить список отделов, как например:

{ "department_id": "1", "отдел": "Технология" },
{ "department_id": "2", «departm ent ":" Людские ресурсы " }

Клиент может включать один из вышеуказанных действующих департаментов. Мой вопрос: должен ли запрос POST/PUT включать идентификатор отдела или имя? Идентификатор кажется более легким для проверки, но менее «дружественным» для клиента. В любом случае мы можем правильно проверить нашу справочную таблицу, но мне интересно, что такое лучшая практика.

Answer 1

Он должен использовать идентификатор. Пользователь API должен понимать ссылки. В этом случае он должен понимать, что он относится к одному конкретному отделу. Для этого клиенту, возможно, придется сначала запросить список доступных отделов, но это не должно вас беспокоить, пока вы выставляете такую ​​конечную точку.

Использование имени отдела сделает имя отдела уникальным ключом, который сильно изменит семантику. Кроме того, вам может потребоваться индексировать название отдела, чтобы эффективно реализовать это, что является еще одним тяжелым недостатком использования имени.

Answer 2

class Employee { 
    long Id; 
    Department Dept; 
} 

или

class Employee { 
     long Id; 
     long DepartmentId; 
    } 

    class Department{ 
     long DepartmentId; 
     string DepartmentName; 
    } 

Это моющее средство для структуры класса. Что касается клиента, им нужен элемент управления выбора для выбора отдела - вы не можете ожидать, что они узнают идентификатор или вернут имя. Я использовал коробку AutoComplete для больших выборов или коробку dropdown для небольшого списка.

Чтобы ответить на вопрос о том, что отправить обратно from клиенту, я пришлю обратно ID.

Answer 3

Как правило, лучше иметь URI, которые передают смысл. Например

www.mylocalpaper.com/news/local/politics/2013_town_budget_approved 

лучше

www.mylocalpaper.com/sections/12/subsection/13/article/45 

, поскольку раздел 12 подраздел 13 статьи 45 ничего никому не значит, что за пределами кода веб-сервера. Очевидно, убедитесь, что URL для каждого отдела уникален (URL-адрес U).

Вы также должны вернуть полный URL-адрес клиенту для отдела, а не просто краткое имя, и использовать этот URL-адрес, чтобы добавить пользователя в этот отдел. Таким образом, возвращение

{ "add_employee_url": "/departments/tech/employees/", "name": "Technology" }, 
{ "add_employee_url": "/departments/hr/employees/", "name": "Human Resources" } 

Затем клиент просто публикует сведения о сотруднике по URL-адресу, соответствующему выбранному. Пользователь клиента выбирает «Технология», а клиент отправляет /departments/tech/employees/.

Если URL-адрес отдела изменяется (скажем, tech становится technology по строке), клиенту все равно, потому что он получает полный URL-адрес для действия.