Partial REST view

gistfile1.md

The Problem:

Good REST design assumes a single URI to identify a given resource. In the enterprise sphere this might cause an unneeded overhead. Take for instance a product entity as an example. Looking at it from a customer point of view you would be interested in information such as name, price, description and availability. From a purchaser point of view (the person in the company buying this product from its suppliers) he doesn't care about the customer prices. He cares about data related to the purchasing of this product such as last_purchased_supplier, suppliers, supplier prices and so on. Again the customer 1)should not care about the purchasing data associated to a product and 2) not be allowed to see it anyhow.

For a record, in SAP a product has more than 100 columns. A sales order item has more than 150 columns, although there are reasons for this complexity needless to say that not everybody needs all data returned.

A Solution:

One solution could be to introduce the concept of a RestResourceView. Basically it would be a schema describing the representation of how the data should need to be returned. A bit similar to a Doctrine ORM/ODM schema. It could allow us to return a partial resource and at the same time describe if some parts of the entity should need to be expanded. Expand syntax an behavior should be similar as described here http://dotheweb.posterous.com/how-to-design-rest-apis-for-mobile#more

For instance:

product_customer_view: entity_name: Product format: json-ld fields: [name, description, price] expand: [categories, options]

->A json ld representation would be returned for the given Product instance with fields name, description and price. Furthermore categories and options nodes are expanded (with a proper json-ld link)

product_purchaser_view: entity_name: Product format: json-ld fields: [name, description, last_purchased_supplier, ] expand: [suppliers , suppliers/supplier/contact]

-> Fields name, description, last_purchased_supplier would be returned, suppliers would be expanded with the contact section of a given supplier expanded aswell.

gistfile1.txt

The Problem:

Good REST design assumes a single URI to identify a given resource.  In the enterprise sphere this might cause an unneeded overhead.  Take for instance a product entity as an example.  Looking at it from a customer point of view you would be interested in information such as name, price, description and availability.  From a purchaser point of view (the person in the company buying this product from its suppliers) he doesn't care about the customer prices.  He cares about data related to the purchasing of this product such as last_purchased_supplier, suppliers, supplier prices and so on.  Again the customer 1)should not care about the purchasing data associated to a product and 2) not be allowed to see it anyhow.

For a record, in SAP a product has more than 100 columns.  A sales order item has more than 150 columns, although there are reasons for this complexity needless to say that not everybody needs all data returned.

A Solution:

One solution could be to introduce the concept of a RestResourceView.  Basically it would be a schema describing the representation of how the data should need to be returned.  A bit similar to a Doctrine ORM/ODM schema.  It could allow us to return a partial resource and at the same time describe if some parts of the entity should need to be expanded.  Expand syntax an behavior should be similar as described here http://dotheweb.posterous.com/how-to-design-rest-apis-for-mobile#more

For instance:

product_customer_view:
  entity_name: Product
  format: json-ld
  fields: [name, description, price]
  expand: [categories, options]


->A json ld representation would be returned for the given Product instance with fields name, description and price.  Furthermore categories and options nodes are expanded (with a proper json-ld link)


product_purchaser_view:
  entity_name: Product
  format: json-ld
  fields: [name, description, last_purchased_supplier, ]
  expand: [suppliers , suppliers/supplier/contact]

-> Fields name, description, last_purchased_supplier would be returned, suppliers would be expanded with the contact section of a given supplier expanded aswell.

partial_rest_view_thoughts

The Problem:

Good REST design assumes a single URI to identify a given resource.  In the enterprise sphere this might cause an unneeded overhead.  Take for instance a product entity as an example.  Looking at it from a customer point of view you would be interested in information such as name, price, description and availability.  From a purchaser point of view (the person in the company buying this product from its suppliers) he doesn't care about the customer prices.  He cares about data related to the purchasing of this product such as last_purchased_supplier, suppliers, supplier prices and so on.  Again the customer 1)should not care about the purchasing data associated to a product and 2) not be allowed to see it anyhow.

For a record, in SAP a product has more than 100 columns.  A sales order item has more than 150 columns, although there are reasons for this complexity needless to say that not everybody needs all data returned.

A Solution:

One solution could be to introduce the concept of a RestResourceView.  Basically it would be a schema describing the representation of how the data should need to be returned.  A bit similar to a Doctrine ORM/ODM schema.  It could allow us to return a partial resource and at the same time describe if some parts of the entity should need to be expanded.  Expand syntax an behavior should be similar as described here http://dotheweb.posterous.com/how-to-design-rest-apis-for-mobile#more

For instance:

product_customer_view:
  entity_name: Product
  format: json-ld
  fields: [name, description, price]
  expand: [categories, options]


->A json ld representation would be returned for the given Product instance with fields name, description and price.  Furthermore categories and options nodes are expanded (with a proper json-ld link)


product_purchaser_view:
  entity_name: Product
  format: json-ld
  fields: [name, description, last_purchased_supplier, ]
  expand: [suppliers , suppliers/supplier/contact]

-> Fields name, description, last_purchased_supplier would be returned, suppliers would be expanded with the contact section of a given supplier expanded as well.


Usages:

GET products/12?view=product_customer
GET products/12?view=product_purchaser_view

Notes:
- If the view name is ommitted the default view should be taken into account.
- Instead of passing it as a parameter it might need to be part of content negotiation through HTTP headers
- The view would be subjected to authorization
- It should be possible by the REST consumer to retrieve allowed views so the client can decide which one to use.

rest_view

The Problem:

Good REST design assumes a single URI to identify a given resource.  In the enterprise sphere this might cause an unneeded overhead.  Take for instance a product entity as an example.  Looking at it from a customer point of view you would be interested in information such as name, price, description and availability.  From a purchaser point of view (the person in the company buying this product from its suppliers) he doesn't care about the customer prices.  He cares about data related to the purchasing of this product such as last_purchased_supplier, suppliers, supplier prices and so on.  Again the customer 1)should not care about the purchasing data associated to a product and 2) not be allowed to see it anyhow.

For a record, in SAP a product has more than 100 columns.  A sales order item has more than 150 columns, although there are reasons for this complexity needless to say that not everybody needs all data returned.

A Solution:

One solution could be to introduce the concept of a RestResourceView.  Basically it would be a schema describing the representation of how the data should need to be returned.  A bit similar to a Doctrine ORM/ODM schema.  It could allow us to return a partial resource and at the same time describe if some parts of the entity should need to be expanded.  Expand syntax an behavior should be similar as described here http://dotheweb.posterous.com/how-to-design-rest-apis-for-mobile#more

For instance:

product_customer_view:
  entity_name: Product
  format: json-ld
  fields: [name, description, price]
  expand: [categories, options]


->A json ld representation would be returned for the given Product instance with fields name, description and price.  Furthermore categories and options nodes are expanded (with a proper json-ld link)


product_purchaser_view:
  entity_name: Product
  format: json-ld
  fields: [name, description, last_purchased_supplier, ]
  expand: [suppliers , suppliers/supplier/contact]

-> Fields name, description, last_purchased_supplier would be returned, suppliers would be expanded with the contact section of a given supplier expanded aswell.

That is exactly what content-types are for.

vnd.myshop.orders.customer_view+json
vnd.myshop.orders.backend_view+json

Etcetc