Як називати ресурси й будувати URL у REST API?

Основні правила:

• Іменники, а не дієслова: дія задається HTTP-методом. GET /orders, POST /orders, DELETE /orders/42 - а не /getOrders, /createOrder.
• Множина для колекцій: /orders і /orders/42 - узгоджено для всього API.
• Вкладеність для відношень, але неглибока: /users/42/orders - так; /users/42/orders/7/items/3/reviews - ні. Ресурс з власним ID краще адресувати напряму: /order-items/3.
• Нижній регістр і дефіси: /payment-methods, а не /paymentMethods чи /payment_methods.
• Фільтрація, сортування, пагінація - у query-параметрах: /orders?status=paid&sort=-created_at&page[size]=20.
• Стабільні ідентифікатори в URL: ID чи UUID, а не назви, які можуть змінитися.

Дії, що не вкладаються в CRUD:

• як під-ресурс стану: POST /orders/42/cancellation;
• як дія-під-ресурс: POST /orders/42/cancel - прагматично й зрозуміло, і так роблять великі API (Stripe, GitHub);
• головне - узгодженість у межах API.

Відповіді:

• Узгоджене іменування полів (snake_case чи camelCase - одне на весь API).
• Дати - в ISO 8601 з часовим поясом.
• Гроші - цілими числами в мінімальних одиницях або рядками, з валютою.
• Посилання на пов'язані ресурси чи їхні ID, а не дублювання цілих об'єктів без потреби.

Найважливіше - передбачуваність: розробник, побачивши два ендпоінти, має вгадати третій. Опис в OpenAPI допомагає тримати цю узгодженість і генерувати клієнти.

Докладніше в документації: REST