EditAttachPrintable
r5 - 2017-01-05 - 19:05:51 - Main.WebsmithYou are here: TWiki >  Deployment Web > WebPreferences > CLMOSLCAPIChangesFor601

CLM OSLC API changes for 6.0.1 todo.png

Authors: LarrySmith
Build basis: Products, editions, or versions that apply to the content. If no build basis applies to this content, set the build basis to None.

This document describes some changes made to the OSLC V2.0 API in RTC Version 6.0.1. The changes were made to enable specific reports that required the API to be more compliant with the standard.

There are two OSLC REST API changes made in 6.0.1 that could potentially break scripts that use the OSLC REST API from prior versions. These changes are considered improvements over previous releases and were necessary for standards compliance and to enable cross-project reporting to work in Report Builder.

  • The first item changes the way enumerations literal URI's are specified in responses.
  • The second item changes the response to a JSON request for an enumeration so it is a JSON object instead of array of literals.

The Resource URI of an Enumeration Literal Changes in RTC Version 6.0.1

RTC allows user to specify “External Value” of enumeration literal. The literal is configured in the project area administration as follows:


oslc-fig1-Low.png

The way this literal is returned in an OSLC response has changed in RTC Version 6.0.1

Before RTC Version 6.0.1: Enumeration without an External Value

Before RTC Version 6.0.1, consider an enumeration literal without an external value:
oslc-fig2-Low.png

Before RTC Version 6.0.1, if user doesn’t specify an “External Value” and then does an OSLC GET on the enumeration literal resource, the literal is referenced with the internal value:

  <rdf:Description rdf:about="https://localhost:9443/ccm/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/priority.literal.1">

For example, a GET request:
oslc-fig3-GET.png
oslc-fig5a-GET-xml.png

would return a response:

<rdf:RDF
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:rtc_cm="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" > 
  <rdf:Description rdf:about="https://localhost:9443/ccm/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/priority.literal.1">
    <rdf:type rdf:resource="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/Literal"/>
    <rtc_cm:iconUrl rdf:resource="https://localhost:9443/ccm/service/com.ibm.team.workitem.common.internal.model.IImageContentService/processattachment/_gxHFEC51EeauNJ_abwY7Dg/enumeration/low.gif"/>
    <dcterms:title rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Low</dcterms:title>
    <dcterms:identifier rdf:datatype="http://www.w3.org/2001/XMLSchema#string">priority.literal.1</dcterms:identifier>
  </rdf:Description>
</rdf:RDF>

This does not change in RTC Version 6.0.1 because there is no external value.

Before RTC Version 6.0.1: Enumeration with an External Value

Before RTC Version 6.0.1, consider an enumeration literal with an external value:
oslc-fig5-Low.png

Before RTC Version 6.0.1, if user does specify an external value and then does an OSLC GET on the enumeration literal resource, the literal is referenced with the external value:

  <rdf:Description rdf:about="https://localhost:9443/ccm/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/low">

Notice how the literal value is used in the reference URI.

For example, a GET request:
oslc-fig6-GET.png

would return a response:

<rdf:RDF
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:rtc_cm="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" > 
  <rdf:Description rdf:about="https://localhost:9443/ccm/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/low">
    <rdf:type rdf:resource="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/Literal"/>
    <rtc_cm:iconUrl rdf:resource="https://localhost:9443/ccm/service/com.ibm.team.workitem.common.internal.model.IImageContentService/processattachment/_gxHFEC51EeauNJ_abwY7Dg/enumeration/low.gif"/>
    <dcterms:title rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Low</dcterms:title>
    <dcterms:identifier rdf:datatype="http://www.w3.org/2001/XMLSchema#string">priority.literal.1</dcterms:identifier>
  </rdf:Description>
</rdf:RDF>

When the external value changes, these URI's will note be valid anymore.

After RTC Version 6.0.1 the URI is Stable

One drawback of the initial implementation is that the enumeration literal resource URI is not stable. The URI can change if the user changes the enumeration value of the enumeration literal. Since the enumeration literal URI is embedded in every work item and enumeration resources referenced, the links and data becomes invalid when the enumeration value changes.

In 6.0.1 release, the URI is made more stable by always using the internal literal value in the reference and adding an owl:sameAs triple in the resource to map the value properly. The value of owl:sameAs triple is the external URI of the enumeration literal.

For more information see Best Practice: Use URIs to Represent Enumerated Values.

After RTC Version 6.0.1: Enumeration with External Value

In RTC Version 6.0.1 and later, consider if user does specify external value for the literal:
oslc-fig5-Low.png

Now when an OSLC GET is requested for the enumeration literal resource, the literal is referenced with the internal value and an owl:sameAs element is added:

  <rdf:Description rdf:about="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/priority.literal.1">
...
    <owl:sameAs rdf:resource="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/low"/>
...

Notice how the literal value is not used in the reference URI and is mapped by the owl:sameAs element. Now the administrator is free to change the literal value without invalidating the links. Because the owl:sameAs resolves the links correctly, the pre-6.0.1 user scenarios is still supported as the literal resource can be accessed using either URI.

For example, a GET request:
oslc-fig6a-GET.png

would return a response:

<rdf:RDF
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:owl="http://www.w3.org/2002/07/owl#"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:j.0="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/"
    xmlns:rtc_cm="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" > 
  <rdf:Description rdf:about="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/priority.literal.1">
    <rdf:type rdf:resource="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/Literal"/>
    <rdf:type rdf:resource="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority"/>
    <owl:sameAs rdf:resource="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/low"/>
    <rtc_cm:iconUrl rdf:resource="https://localhost:9443/jazz/service/com.ibm.team.workitem.common.internal.model.IImageContentService/processattachment/_gxHFEC51EeauNJ_abwY7Dg/enumeration/low.gif"/>
    <dcterms:title rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Low</dcterms:title>
    <dcterms:identifier rdf:datatype="http://www.w3.org/2001/XMLSchema#string">priority.literal.1</dcterms:identifier>
  </rdf:Description>
</rdf:RDF>

The new URI format is more stable for some configurations.

Enumeration Requests Return a JSON Object instead of an Array

Before RTC Version 6.0.1, when user gets an application/json representation of an enumeration resource, the returned resource was returned as a JSON array of enumeration literals. However, array returned for the enumeration resource does not contain any information about the enumeration itself. It only lists the enumeration literals. In 6.0.1, a JSON object is returned instead, and this includes information about enumeration itself in the resource representation.

Before RTC Version 6.0.1: Enumeration JSON Response

For example, before RTC Version 6.0.1, a GET request:
oslc-fig9-GET-json.png

would return an array as a response.

[
   {
      "rdf:type":[
         {
            "rdf:resource":"http:\/\/jazz.net\/xmlns\/prod\/jazz\/rtc\/cm\/1.0\/Literal"
         }
      ],
      "rtc_cm:iconUrl":"https:\/\/localhost:9443\/ccm\/service\/com.ibm.team.workitem.common.internal.model.IImageContentSe
rvice\/processattachment\/_gxHFEC51EeauNJ_abwY7Dg\/enumeration\/low.gif",
      "dcterms:title":"Low",
      "rdf:about":"https:\/\/localhost:9443\/ccm\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority\/priority.literal.1",
      "dcterms:identifier":"priority.literal.1"
   },
   
   {
      "rdf:type":[
         {
            "rdf:resource":"http:\/\/jazz.net\/xmlns\/prod\/jazz\/rtc\/cm\/1.0\/Literal"
         }
      ],
      “rtc_cm:iconUrl":"https:\/\/localhost:9443\/ccm\/service\/com.ibm.team.workitem.common.internal.model.IImageContentSe
rvice\/processattachment\/_gxHFEC51EeauNJ_abwY7Dg\/enumeration\/high.gif",
      "dcterms:title":"High",
      "rdf:about":"https:\/\/localhost:9443\/ccm\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority\/priority.literal.2",
      "dcterms:identifier":"priority.literal.2"
   }
]

The array only provides information about the literals and does not contain any information about the enumeration.

After RTC Version 6.0.1: Enumeration JSON Response

After RTC Version 6.0.1, the resource is returned as a a JSON object. For example, in RTC Version 6.0.1, a GET request:
oslc-fig10-GET-json.png

now returns a JSON object as a response:

{
   "rdf:type":
      [
         {
            "rdf:resource":"http:\/\/www.w3.org\/2000\/01\/rdf-schema#Class"
         }
      ],
   "rdf:about":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority",
   "acc:accessContext":
      {
         "rdf:resource":"https:\/\/localhost:9443\/jazz\/acclist#_gxHFEC51EeauNJ_abwY7Dg"
      },
   "prefixes":
      {
         "rtc_cm":"http:\/\/jazz.net\/xmlns\/prod\/jazz\/rtc\/cm\/1.0\/",
         "oslc":"http:\/\/open-services.net\/ns\/core#",
         "owl":"http:\/\/www.w3.org\/2002\/07\/owl#",
         "rdf":"http:\/\/www.w3.org\/1999\/02\/22-rdf-syntax-ns#",
         "acc":"http:\/\/open-services.net\/ns\/core\/acc#",
         "dcterms":"http:\/\/purl.org\/dc\/terms\/"
      },
   "oslc:results":
      [
         {
            "rdf:type":
               [
                  {
                     "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority"
                  },
                  {
                     "rdf:resource":"http:\/\/jazz.net\/xmlns\/prod\/jazz\/rtc\/cm\/1.0\/Literal"
                  }
               ],
            "rtc_cm:iconUrl":"https:\/\/localhost:9443\/jazz\/service\/com.ibm.team.workitem.common.internal.model.IImageContentSe
rvice\/processattachment\/_gxHFEC51EeauNJ_abwY7Dg\/enumeration\/low.gif",
            "dcterms:title":"Low",
            "rdf:about":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority\/priority.literal.1",
            "dcterms:identifier":"priority.literal.1"
         },
         {
            "rdf:type":
               [
                  {
                     "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority"
                  },
                  {
                     "rdf:resource":"http:\/\/jazz.net\/xmlns\/prod\/jazz\/rtc\/cm\/1.0\/Literal"
                  }
               ],
            "rtc_cm:iconUrl":"https:\/\/localhost:9443\/jazz\/service\/com.ibm.team.workitem.common.internal.model.IImageContentSe
rvice\/processattachment\/_gxHFEC51EeauNJ_abwY7Dg\/enumeration\/high.gif",
            "dcterms:title":"High",
            "rdf:about":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority\/priority.literal.2",
            "dcterms:identifier":"priority.literal.2"
         }
      ]
}

Here we see more information about the Enumeration available in the object attributes.

External links:

Referenced Items:

Edit | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r6 < r5 < r4 < r3 < r2 | More topic actions...
 
This site is powered by the TWiki collaboration platformCopyright © by IBM and non-IBM contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use. Please read the following disclaimer.
Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.