Лучшие практики REST API для маршрутов

Question

Интересно, что является лучшим методом при создании API REST для следующего сценария ios, когда Заказ является ресурсом:

1. Получить все заказы в Базе данных. (конечно, не практический сценарий, только для понимания цели)
2. Получить заказы по идентификаторам заказов.
3. Получить один заказ по идентификатору заказа

• Может один GET маршрут будет использоваться для всех этих сценариев ios?

• Или у нас должны быть отдельные маршруты для этих сценариев ios?

Любая помощь будет принята с благодарностью !! (Express JS framework используется, если это имеет значение)

Answer 1

Можно ли использовать один маршрут GET для всех этих сценариев ios?

Вы можете использовать один маршрут для всех этих сценариев ios:

GET /orders                              // get all
GET /orders?id=409,5678,2987             // get these orders by id
GET /orders?id=9463                      // get this order by id
GET /orders?person=jackwelch             // get orders for this person
GET /orders?company=aaWidget             // get orders for this company 

Или у нас должны быть отдельные маршруты для этого сценария ios?

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

И помните, что для добавления нового заказа вы бы использовать POST и модифицировать существующий заказ, вы будете использовать PUT и удалять заказ, вы используете DELETE

POST   /orders                    // create new order, data in body of request
PUT    /orders/:id                // modify existing order, data in body of request
DELETE /orders/:id                // delete an order

Итак, все это можно сделать с помощью одной /orders структуры URL для внешнего мира. Внутренне, он, вероятно, будет структурирован как несколько разных обработчиков маршрутов, просто чтобы сделать код для его обработки более простым:

app.get("/orders", ...);         // handle order queries   (use req.query)
app.post("/orders", ...);        // create new order       (use req.body)
app.put("/orders/:id", ...);     // modify existing order  (use req.params.id and req.body)
app.delete("/orders/:id", ...);  // delete existing order  (use req.params.id)

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

Answer 2

API RESTful используют методы HTTP в качестве глаголов. Это означает, что одна и та же конечная точка должна использоваться для получения списка заказов и создания нового; или получите один указанный c заказ, обновите его или удалите событие.

Имея это в виду, вы можете разработать структуру API следующим образом:

GET       /orders        // To get a list of all orders
GET       /orders/:id    // To get information about a specific order

Это поможет вам добавить несколько методов довольно легко, без изменения структуры API:

POST     /orders         // To create a new order
PUT      /orders/:id     // To update that specific order
DELETE   /orders/:id     // To delete it

Если вы хотите добавить возможности поиска в конечную точку, довольно часто используется строка запроса. Например:

GET   /orders?email=john@example.org  // To retrieve all orders from that customer
GET   /orders?limit=10                // To retrieve only 10 hits per results
GET   /orders?limit=10&total=99.99    // To retrieve top 10 orders with a total of 99.99

Вы можете добавить выделенные параметры поиска для возврата заказов по идентификаторам (в соответствии с запросом), но это не так часто, так как вы уже можете запросить по идентификатору, используя конечную точку /orders/:id. Вы можете подумать об избежании лишних запросов здесь, но, вообще говоря, выигрыш в производительности довольно низок - , за исключением случаев, когда для вашего приложения важно получить по идентификаторам несколько попаданий.