api - ticket - ¿Cómo estructurar la jerarquía de recursos REST?

zendesk api v2 tickets json

Question

Soy nuevo en el desarrollo web del lado del servidor y recientemente he estado leyendo mucho sobre la implementación de APIs RESTful. Un aspecto de las API de REST en el que todavía estoy atascado es cómo estructurar la jerarquía URI que identifica los recursos con los que el cliente puede interactuar. Específicamente estoy atascado en decidir qué tan detallado será la jerarquía y qué hacer en el caso de que los recursos estén compuestos de otros tipos de recursos.

Aquí hay un ejemplo que espero que muestre lo que quiero decir. Imagina que tenemos un servicio web que permite a los usuarios comprar productos de otros usuarios. Entonces, en este caso simple, hay dos recursos y usuarios de recursos de nivel superior. Así es como comencé a estructurar la jerarquía URI,

Para los usuarios:

/users
      /{id}
           /location
           /about
           /name
           /seller_rating
           /bought
           /sold

Para productos:

/products
         /{id}
              /name
              /category
              /description
              /keywords
              /buyer
              /seller

En ambos casos, los objetos en cada jerarquía hacen referencia a un subconjunto de los objetos en la otra jerarquía. Por ejemplo, /users/{id}/bought es una lista de los productos que algún usuario ha comprado, que es un subconjunto de /products . Además, /products/{id}/seller referencia al usuario que vendió un producto específico.

Dado que estos URI hacen referencia a otros objetos, o subconjuntos de otros objetos, ¿debería la API soportar cosas como esta: /users/{id}/bought/id/description y /products/{id}/buyer/location ? Porque si esos tipos de URI son compatibles, ¿qué hay para detener algo como esto /users/{id}/bought/{id}/buyer/bought/{id}/seller/name , o algo igualmente complicado? Además, en este caso, ¿cómo manejaría el enrutamiento ya que el enrutador en el servidor tendría que interpretar los URI de longitud arbitraria?

Answer 1

Debería pensarlo de manera CRUD, donde cada entidad admite Crear, Leer, Actualizar y Eliminar (normalmente utilizando los verbos GET, POST, PUT y DELETE HTTP respectivamente).

Esto significa que sus puntos finales normalmente solo irán a un nivel de profundidad. Por ejemplo

Usuarios

GET    /users       - Return a list of all users (you may not want to make this publically available)
GET    /users/:id   - Return the user with that id
POST   /users      - Create a new user. Return a 201 Status Code and the newly created id (if you want)
PUT    /users/:id   - Update the user with that id
DELETE /users/:id  - Delete the user with that id

Ir a más detalles, como /users/:id/about probablemente no sea necesario. Si bien puede funcionar, puede que se esté volviendo un poco exagerado.

Quizás en tu caso puedas agregar:

GET    /users/:id/bought - Array of products that the user bought
GET    /users/:id/sold   - Array of products that the user sold

donde puede devolver una lista de identificadores (que se pueden obtener a través de la API de productos), o puede rellenar los Productos antes de devolverlos si lo desea. Si elige rellenarlos, probablemente no debería llenar los usuarios a los que hace referencia cada producto. Esto conducirá a que incluye circular y está mal.

Y para Productos, en su ubicación yo usaría:

GET    /products- Return a list of all products
GET    /products/:id   - Return the products with that id
POST   /products- Create a new product. Return a 201 Status Code and the newly created id (if you want)
PUT    /products/:id   - Update the product with that id
DELETE /products/:id  - Delete the product with that id

GET    /products/:id/buyers     - Array of who bought the product
GET    /products/:id/sellers    - Array of everyone selling the product

Answer 2

El objetivo es crear identificadores de recursos convenientes, no intente hacer una referencia cruzada de todo. No tienes que repetir las relaciones de tu base de datos en la representación de URL :)

Los enlaces como /product/{id}/buyer nunca deben existir, porque ya hay un identificador para ese recurso: /user/{id}

Aunque está bien tener /product/{id}/buyers-list porque la lista de compradores es una propiedad del producto que no existe en otros contextos.