Geek Answers Handbook

REST Resource Path Design

I am developing a REST service and I am trying to adhere to the conventions and recommendations of Dr. Roy Fielding.

I present my service as an endpoint that provides a set of resources. A resource is identified by a URI, and api clients can manipulate resources using HTTP semantics (i.e., various HTTP verbs are mapped to corresponding operations on the URI).

The Guidelines state that these URIs must be defined in a hierarchical manner, reflecting the hierarchy of objects. This is useful for creating resources, because on the backend we need data to perform the create operation. However, with further manipulations, most of the information included in the URI will not even be used by the service, because, as a rule, only a resource identifier is enough to uniquely identify the purpose of the operation.

Example. Consider Api, which provides product creation and management. Please also note that the product is associated with the brand. When creating, it makes sense that the following action is performed: HTTP POST / Brand / {brand_id} / Product [Body containing the input required to create the product]

Create returns an HTTP 201 created with a location header that displays the newly created product location.

With further manipulations, customers can access the product by doing: HTTP PUT / Brand / {brand_id} / Product / {product_id} HTTP DELETE / Brand / {brand_id} / Product / {product_id}, etc.

However, since the product identifier is universal in the product domain, the following manipulations can be performed as follows: / Product / {product_id} I adhere to the prefix / Brand / {brand_id} for reasons of consistency. In fact, the brand identifier is ignored by the service. Do you think this is good practice and reasonable to maintain a clear, unambiguous definition of ServiceInterface? What are the benefits of this, and is it at all?

Any pointers to best practices for determining URIs will also be appreciated.

Thank you in advance

+4
2

:

, URI , .

, RESTful API. REST. :

API REST ( ).

API REST URI...

URL-, . API RESTful , URL- URI. ( URI , , "RESTfullness", .)

URI "" , , . ( , ?). . , ( ). REST , . / .

, .

POST/product/ /brand/xzy .

, , GET/brand/xzy. , , GET/brand/{id}/products URL (/brandproducts/xzy /34143453453) .

URI, , . , , API.

+8

, :

.

, . , , . (GET, PUT ..), , , . ( , --, --, --) .

, , api.example.com:

GET /product/12345

. XML , XHTML, JSON . , 12345:

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Length: ...

<?xml version="1.0"?>
<Product href="http://api.example.com/product/12345" rel="self" type="application/xml"/>
  <Name>Macaroni and Cheese</Name>
  <Brand href="http://api.example.com/brand/7329" type="application/xml"/>
  <Manufacturer href="http://api.example.com/manufacturer/kraft" rel="parent" type="application/xml"/>
</Product>

, 12345, . , HATEOAS :

  • .
  • ( "rel" ). "self" "parent" - , .
  • MIME, . , , .
  • URL- . "" URL-, , - . , URL- (, "/brands/kraft" ).

, , . , , . . , 12345:

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Length: ...

<?xml version="1.0"?>
<Product href="http://api.example.com/product/12345" rel="self" type="application/xml"/>
  <Name>Macaroni and Cheese</Name>
  <Brand href="http://api.example.com/brand/7329" rel="parent" type="application/xml"/>
  <Manufacturer href="http://api.example.com/manufacturer/kraft" type="application/xml"/>
  <!-- Other product data -->
  <Related>
    <Product href="http://api.example.com/product/29180" rel="prev" type="application/xml"/>
    <Product href="http://api.example.com/product/39201" rel="next" type="application/xml"/>
  </Related>      
</Product>

"prev" "next" . "" "" "", "". "" "" rel, "prev" "next". .

+1

More articles:


All Articles