Правила названий ручек (endpoint)

• 1. Основные правила структуры URI
• 2. Рекомендации по читаемости
• 3. Паттерны для параметров:
• 4. Лучшие практики
• Примеры правильного нейминга:
  • Как искать на RFC Editor:
  • Дополнительные ресурсы:

Здесь собраны основные правила нейминга ручек со ссылками на первоисточник. В роли первоисточника — RFC документ¹.

---

1. Основные правила структуры URI

• RFC 3986: Uniform Resource Identifier (URI) Syntax²
  • Используйте lowercase для путей и параметров.
  • Разделяйте слова через дефис: /user-profiles, а не camelCase или snake_case.
  • Избегайте специальных символов, кроме -, ., _, ~.
• Ссылка.

---

2. Рекомендации по читаемости

• RFC 7230: HTTP/1.1 Message Syntax

• Ссылка.

---

3. Паттерны для параметров:

• RFC 6570: URI Templates
  • Шаблоны переменных: /users/{userId}/posts/{postId}.
  • Кодирование query параметров: ?filter=active&sort=name.
• Ссылка.

---

4. Лучшие практики

• RFC 9110: HTTP Semantics (обновление RFC 7231)
  • Версионирование API: /v1/resource, /v2/resource.
  • Используйте множественное число для коллекций: /products, а не /product.
• Ссылка.

---

Примеры правильного нейминга:

Неправильно	Правильно
/getUser	/users/{id}
/updateOrder	/orders/{id} (метод PUT)
/api/get_all_posts	/api/v1/posts

---

Как искать на RFC Editor:

Я привел наиболее часто используемые правила, которые встречаю в своей практике. У вас могут быть другие кейсы, которые вы можете найти по следующим шагам:

1. Перейдите на https://www.rfc-editor.org.
2. Введите ключевые слова в поиск: URI syntax, REST API naming, HTTP semantics.
3. Отфильтруйте результаты по дате (актуальные RFC имеют статус Internet Standard).

Дополнительные ресурсы:

• REST API Tutorial: Naming Conventions.
• Microsoft REST API Guidelines: URI Design.

1. Request for Comments, RFC) — документ из серии пронумерованных информационных документов Интернета
2. Uniform Resource Identifier — унифицированный (единообразный) идентификатор ресурса