Resource Format

Overview

The goal of this document is to define extra requirements on the data returned by the RESTful service to enable reporting, details about resources in specific domain will be described in specification for each domain separately.

Identifying properties

To be more concrete, following are two different ways to organize data, and their implications based on the above assumption.

1. Option 1

If the data is represented in a generic way like this:

<attribute>

    <name>att1</name>

    <value>value1</value>

</attribute>

<attribute>

    <name>att2</name>

    <value>value2</value>

</attribute>  

We can identify "name" and "value" of the "attribute", we will get a list of generic attributes like this (logically):

The benefit is, we deal with the attributes in a generic way, this allow us to support new, custom attributes without changes. The disadvantage is, we can't deal with each attribute using specific logic since we can't tell one attribute from the other.

2. Option 2

If the data is like this:

<att1>value1</att1>

<att2>value2</att2> 

Then we can identify "att1" and "att2", we will get specific attributes like this (logically)

The benefit is, we can deal with each attribute with specific logic. The disadvantage is, we can't support new, custom attributes without changes.

Extracting data

The reporting consumer should be able to extract real content for the properties from the resultset directly. That means, the service provider should return real content for properties in the resultset and the reporting consumer shouldn't be forced to follow URLs to retrieve real content for properties.

Identifying resources

Each resource MUST be globally uniquely identifiable.

Choices for identifier:

1. absolute URI reference

... (other choices?)

Resource deletion

Options considered
1. soft delete with an indicator marking record as logically deleted.
2. add a REST API to get all deleted records since a date-time.
3. reporting client to request individual records one at a time to validate existence.
4. reporting cleint query to get resource URL (or an unique identifier if exist) for all current records (excluding hard and soft deleted). It would be reporting client's responsibility to map work what has been deleted in its data repository.

Option 4 is chosen for

• no new REST API needed
• performance

Note: Service Provider should aware of this use case and optimize if feasible.

Last update date

In order to participate in delta loading for changed records, each OSLC resource need to have property dc:modified.

The reporting consumer can query on the dc:modified property to get records modified since a date-time.

Paging

Proposal:

<oslc_rm:Requirements rdf:about="xxx.example.com/Requirements">

<oslc:PageContext
oslc:nextPage="http://xxx.exmaple.com/4563EFA899"/>

<!--actual content for Requirements -->

</oslc_rm:Requirements>

Original email from ArthurRyman :

<oslc:PageContext
oslc: thisPage ="http://braintwistors.example.com/ems10/Estimate?oslc:select=ems:select=dc:title,dc:identifier&oslc:where=ems:scenario{ems:project{dc:identifier=4201}}&oslc:pageSize=100"
oslc: nextPage ="http://braintwistors.example.com/ems10/Estimate?oslc:select=ems:select=dc:title,dc:identifier&oslc:where=ems:scenario{ems:project{dc:identifier=4201}}&oslc:pageSize=100&oslc:page=2"
oslc: firstPag e="http://braintwistors.example.com/ems10/Estimate?oslc:select=ems:select=dc:title,dc:identifier&oslc:where=ems:scenario{ems:project{dc:identifier=4201}}&oslc:pageSize=100"
oslc lastPage ="http://braintwistors.example.com/ems10/Estimate?oslc:select=ems:select=dc:title,dc:identifier&oslc:where=ems:scenario{ems:project{dc:identifier=4201}}&oslc:pageSize=100&oslc:page=2"
>

<oslc: select >ems:select=dc:title,dc:identifier</oslc:select>
<oslc: where >ems:scenario{ems:project{dc:identifier=4201}}</oslc:where>
<oslc: pageSize >100</oslc:pageSize>
<oslc: numberOfPages >2</oslc:numberOfPages>
<oslc: page >1</oslc:page>

</oslc:PageContext>

Comments

Add your comments here:

Suggest on "identifying properties" List out a potential usage example for each option: e.g. a listing reporting lists all attributes vs. analysing a measure based on a custom attribute as a dimension.

-- TackTong - 12 Nov 2009

All REST resource has an URI by definition. I guess the reqt. is do we need the URI to be surfaced as a property of the resource? or we can get from rdf:about?

From Reporting System perspective, does it matter what the id is as long as there is one?

-- TackTong - 12 Nov 2009

-- XiangDongHu - 03 Nov 2009