URI и ресурсы

Uniform Resource Identifier 

URI — последовательность символов, идентифицирующая абстрактный или физический ресурс. Cимвольная строка, позволяющая идентифицировать какой-либо документ, изображение, файл, службу, ящик электронной почты и т. д. 

URI в HTTP идентифицирует ресурс.

URI cостоит из:

• URI-reference — это общая ссылка на ресурс, которая может быть как абсолютной, так и относительной. Важно, что ссылка может быть неполной и зависеть от контекста, в котором она используется.
• Absolute-URI — это полная ссылка на ресурс, в которой указаны все компоненты, включая схему, хост, порт, путь и, возможно, query.
  Пример: https://www.example.com:80/path/to/resource?query=value
• Relative-part — это относительная часть URI, которая может указывать только путь или строку запроса без указания хоста или схемы.
  Пример: /path/to/resource
• Authority — это компонент URI, который описывает, кто управляет ресурсом. Включает в себя хост (доменное имя или IP-адрес) и порт.
  Пример: www.example.com:80 
• Uri-host — это конкретно хост в URI, который может быть доменом или IP-адресом.
  Пример: www.example.com или 192.168.1.1. 
• Port — это номер порта, через который клиент и сервер взаимодействуют. Если порт не указан, используется порт по умолчанию для данного протокола (например, 80 для HTTP или 443 для HTTPS).
  Пример: :80 или :443
• Path-abempty — это путь к ресурсу. Указывает на конкретное местоположение ресурса на сервере.
  Пример: /uploads/img/img1
• Segment — это отдельная часть пути. В URI пути могут быть разделены на сегменты с помощью символа /.
  Пример: в URI /uploads/img/img1 сегментами будут uploads, img и img1
• Query — это дополнительные параметры для ресурса. Начинаются с символа ? и состоит из пар "ключ=значение".
  Пример: ?query=value&otherparam=othervalue

HTTP и HTTPS

Схема URI «http» нужна для создания идентификаторов в пространстве имен потенциального сервера HTTP, прослушивающим соединения TCP на заданном порту. Если порт пуст или не указан, по умолчанию используется TCP 80 (зарезервированный порт для служб WWW). 

Схема URI «https» аналогично «http», но способно устанавливать безопасное TLS-соединение, защищенное для HTTP-коммуникации. Это означает, что сервер аутентифицирован от имени указанного органа, и все HTTP-коммуникации с ним имеют конфиденциальность и защиту целостности, приемлемые как для клиента, так и для сервера. Ожидается, что сервер будет использовать закрытый ключ, соответствующий сертификату, который клиент считает заслуживающим доверия для идентифицированного исходного сервера. Это помогает предотвратить атаки, связанные с подменой сервера (например, MITM — атака "человек посередине").

Нормализация

Когда HTTP-сервера обрабатывают URI, они могут выполнять:

• Удаление порта, если это стандартный порт (например, порт 80 для http или порт 443 для https).
• Преобразование хоста в нижний регистр (всегда).
• Замену экранированных символов на их обычные представления.

Эквиваленты:
http://example.com:80/~smith/home.html
http://EXAMPLE.com/%7Esmith/home.html
http://EXAMPLE.com:/%7esmith/home.html

Источник: RFC9110, Internet Engineering Task Force (IETF)

Рекомендации для URI ресурса (за рамками RFC):

1. Существительные для ресурсов

Хорошо: /users, /posts, /orders
Плохо: /createUser, /getPost, /updateOrder

2. HTTP методы для определения действия/глагола

Пример:
GET /users — получение списка пользователей
GET /users/123 — получение информации о пользователе с ID 123
POST /users — создание нового пользователя
PUT /users/123 — обновление информации о пользователе с ID 123
DELETE /users/123 — удаление пользователя с ID 123

3. Иерархия структуры вложенных ресурсов

Хорошо: /users/123/posts — все посты пользователя с ID 123
Плохо: /posts/123/users — неправильное отображение иерархии

4. Множественное число для коллекций

Хорошо: /users, /orders, /products
Плохо: /user, /order, /product

5. Query для фильтрации и сортировки

Примеры:
GET /products?page=2&limit=50 — пагинация товаров, где на странице 50 товаров
GET /users?age=30&country=RU — получение пользователей, которым 30 лет и которые из РФ

6. Версионирование API

7. Гипермедиа (ссылки) в представлениях (отдавать href в ответах)

Дополнительно о URI, URL и URN:

URI — это общее обозначение для всех видов идентификаторов ресурса (включает как URL, так и URN).

URL — это тип URI, который указывает местоположение ресурса и используется для его доступа.

URN — это тип URI, который не указывает местоположение ресурса, а лишь предоставляет уникальный идентификатор.