In a nutshell, the API described below allows you to get, create, modify and query work items and other resources using standard HTTP methods, allowing integrations with minimal requirements for the clients. The API adheres to the OSLC CM Specification. Clients that use only the OSLC subset can also talk to ClearQuest and potentially more Change Management applications in the future. Sections that describe functionality outside of the OSLC spec are marked as such.

This document is non-normative. It provides a summary of the OSLC CM Rest API, along with shell script examples based on curl that illustrate the concepts in more detail. The example snippets assume that you are authenticated to a server configured for form-based auth. Appendix A provides an example of how to do this.

Some things that can be done with the API:

• Load work items in different formats like JSON, XML, ATOM, HTML and in different levels of granularity
• Update work items by modifying the JSON or XML representation and storing it back
• Create work items by obtaining an HTML creation dialog module
• Create work items by posting their JSON or XML representation to a factory URL
• Add or remove links
• Query work items (full text and structured queries)
• Query work items by obtaining an HTML picker module

Discovery

Clients that work with RTC or another implementation of the OSLC spec need a way to discover which functionality is offered by the implementation and where it is surfaced. Clients should not rely on specific URLs or perform path math on URLs. Instead, they should use the discovery chain offered by RTC. Here's an outline of the process to find the Change Management functionality:

1. The root document is exposed at https://<server>:<port>/<app>/rootservices. In a typical RTC testbed, this is https://localhost:9443/jazz/rootservices
2. Fetch this document and extract the Change Management Catalog URL (pointed to by rdf:resource) of the element

   <oslc_cm:cmServiceProviders rdf:resource="https://localhost:9443/jazz/oslc/workitems/catalog"/>

3. Fetch the document behind this URL. It contains a list of ServiceProvider elements that point to the documents which contain the actual service descriptions. In the case of RTC, there is one ServiceProvider element for each Project Area. Typically, an application would use the title of this element to allow the user to choose between the project areas.

         <oslc_disc:ServiceProvider>
            <dc:title>JUnit Project</dc:title>
            <oslc_disc:details rdf:resource="https://localhost:9443/jazz/process/project-areas/_9BHm0EqVEd6HXO10niqZpg"/>
            <oslc_disc:services rdf:resource="https://localhost:9443/jazz/oslc/contexts/
                                             _9BHm0EqVEd6HXO10niqZpg/workitems/services.xml"/>
            <jp:consumerRegistry rdf:resource="https://localhost:9443/jazz/process/project-areas/
                                               _9BHm0EqVEd6HXO10niqZpg/links"/>
         </oslc_disc:ServiceProvider>

4. 
   
5. Fetch the services document pointed to by oslc_disc:services. This document contains links to the dialog modules, to the factory URL to create new work items and to the work item collection URL that allows to query work items.

Another discovery entry point is described in Link Rendering / Compact Rendering.

Resource representations themselves expose references to other resources as hyperlinks. In this case, too, a client needs no knowledge about how to assemble a URL to fetch e.g. the owner or priority representation.

Getting Resource Representations

As mentioned in the Discovery section, a client should generally not care about a specific URL format, but use the discovery mechanisms whenever possible. The format is documented here for completeness and for the case where only the ID or itemId of a work item is known.

Work items are exposed under their Location URI. These URIs are typically obtained by a query or by using a reference from another work item. Two examples of Location URIs:

https://localhost:9443/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/262
https://localhost:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_Kk8YQFElEd6wrL4Qi7w25Q

There is an alternative URL format which is mostly used for non-work item artifacts like enumeration literals, users etc. In contrast to the Location URI format, this format allows to address sub-resources like a link collection or the work item's comments. Using this format, the media type can be specified using an extension like .xml or .json for easier testing in a browser during development time. Some examples:

https://localhost:9443/jazz/oslc/workitems/821.xml
https://localhost:9443/jazz/oslc/workitems/821.json
https://localhost:9443/jazz/oslc/workitems/_Kk8YQFElEd6wrL4Qi7w25Q.json
https://localhost:9443/jazz/oslc/workitems/821/rtc_cm:comments.atom

Multiple representations of a work item are available by specifying an Accept HTTP header or by specifying the required content type as an URL parameter _mediaType. These work for all URL exposed in a resource representation. Specifying an extension works only for the non-Location URI format. The first option is suitable for programmatic use, the second and third options are necessary when you have no control over the Accept header, e.g. in a browser or iFrame.

Supported content types (see OSLC CM Media Types for a normative reference). Note: the discovery documents are only available in XML.

Getting Partial Representations

The properties of a work item that are needed by an application vary with the use case. Presenting a simple query result may only require the work item id and its summary. For other applications, only work item links may be important, including some properties of the link targets. Those should be retrievable in one round-trip. To cover these varying demands, OSLC specifies the concept of Selective Properties, which allows clients to choose the needed properties using the oslc_cm.properties=propA,propB URL parameter. Properties can be specified hierarchically, which allows to inline properties of referenced resources, e.g. the owner name or the type icon.

The JSON, XML (and XHTML) representations fully support Selective Properties. ATOM to some extent, HTML (Hover) not yet. Note: while OSLC specifies the mechanism of how to inline attributes of referenced resources, those resources (like a user or a priority) are not specified by OSLC.

Examples

Get a work item in a specific representation using the Accept header:

URL="https://localhost:9443/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/821"
curl -k  -b $COOKIES -o "wi-821.json" -H "Accept: application/x-oslc-cm-changerequest+json" $URL

Get the same work item using an URL parameter:

https://localhost:9443/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/821
?_mediaType=application/x-oslc-cm-changerequest%2Bjson

Get the same work item using the alternative URL format:

https://localhost:9443/jazz/oslc/workitems/821.json

Get a work item with only the summary and id in the representation:

https://localhost:9443/jazz/oslc/workitems/821.json?oslc_cm.properties=dc:identifier,dc:title

Output:

{
    "dc:title":"a better summary",
    "rdf:resource":"https:\/\/localhost:9443\/jazz\/resource\/itemOid\/
                    com.ibm.team.workitem.WorkItem\/_drv9oFdSEd6YyMDUky_TYw",
    "dc:identifier":821
}

Get a work item with only the summary, the id, the type (inlined with all its properties) and the owner (name inlined):

https://localhost:9443/jazz/oslc/workitems/821.json?oslc_cm.properties=dc:identifier,dc:title,dc:type{*},rtc_cm:ownedBy{dc:title}

Output:

{
    "dc:type":
    {
        "rtc_cm:dimmedIconUrl":"https:\/\/localhost:9443\/jazz\/service\/
                               com.ibm.team.workitem.common.internal.model.IImageContentService\/
                               plugin\/com.ibm.team.workitem.common\/icons\/obj16\/wi_enhancmt_dim.gif",
        "rtc_cm:projectArea":
        {
            "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/projectareas\/_gbb_0EqVEd6HXO10niqZpg"
        },
        "dc:title":"Enhancement",
        "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/types\/_gbb_0EqVEd6HXO10niqZpg\/enhancement",
        "dc:identifier":"enhancement",
        "rtc_cm:category":"com.ibm.team.workitem.workItemType",
        "rtc_cm:iconUrl":"https:\/\/localhost:9443\/jazz\/service\/
                          com.ibm.team.workitem.common.internal.model.IImageContentService\/
                          plugin\/com.ibm.team.workitem.common\/icons\/obj16\/wi_enhancmt.gif"
    },
    "dc:title":"a better summary",
    "rdf:resource":"https:\/\/localhost:9443\/jazz\/resource\/itemOid\/
                    com.ibm.team.workitem.WorkItem\/_drv9oFdSEd6YyMDUky_TYw",
    "dc:identifier":821,
    "rtc_cm:ownedBy":
    {
        "dc:title":"Unassigned",
        "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/users\/_YNh4MOlsEdq4xpiOKg5hvA"
    }
}

Querying Work Items

Queries are run by appending the parameter ?oslc_cm.query=[query] to the simpleQuery URL from the services discovery document:

<oslc_cm:simpleQuery>
   <dc:title>CQL based change request queries</dc:title>
   <oslc_cm:url>https://localhost:9443/jazz/oslc/contexts/_9BHm0EqVEd6HXO10niqZpg/workitems</oslc_cm:url>
</oslc_cm:simpleQuery>

The query syntax is explained in CM Query Syntax.

For instance the query for all work items that contain the word "NPE" can be written as oslc_cm:searchTerms="NPE", and the complete URL would be:

https://localhost:9443/jazz/oslc/contexts/_9BHm0EqVEd6HXO10niqZpg/workitems
?oslc_cm.query=oslc_cm%3AsearchTerms%3D%22NPE%22

The results can be fetched in JSON, ATOM, XML and XHTML as described in Getting Resource Representations. Getting partial representations is especially useful in conjunction with query results as getting only a small set of attributes improves performance considerably and also reduces bandwidth.

To try a query in the browser, you can use the media type extensions .json, .atom, .xml, .xhtml, e.g.:

https://localhost:9443/jazz/oslc/contexts/_9BHm0EqVEd6HXO10niqZpg/workitems.atom
?oslc_cm.query=oslc_cm%3AsearchTerms%3D%22NPE%22

Supported Queryable Attributes

Not all attributes of a work item are queryable. Large strings for instance are not queryable on the database, 'Link attributes' are currently not supported yet (see Task 86401). The following table provides an overview of the supported attributes by type. See Appendix B for the list of supported work item attributes.

Attribute Type	Supported	Remarks
Small String/Html		The asterisk wildcard can be used at the beginning and the end of the value. E.g. "*Test" = "ends with 'Test'", "Test*" = "starts with 'Test'", "*Test*" = "contains 'Test'"
Medium String/Html		The asterisk wildcard can be used at the beginning and the end of the value
Large String/Html		Not directly queryable. A full text query (oslc_cm:searchTerms) can be used instead
Integer, Long, Duration
Boolean
All Item Types*		Both the full URL of the item resource or the itemId can be used as the value
Contributor		The variable {currentUser} can be used as a value (in addition to URL/itemId). It refers to the authenticated user.
Iteration		The variable {current milestone} can be used as a value (in addition to URL/itemId). It refers to the iterations that are marked as current.
Timestamp		In addition to a RFC3339 value, relative times can be used: {[-]number[min|h|d|m|y]} E.g. {-1h} would refer to "our hour ago"
Enumerations		Both the full URL of the literal resource or its identifier can be used as the value
Status		In addition to the status identifier, the variables {open}, {closed}, {progress} and {incomplete} (open or in progress) can be used, too.
Resolution		The resolution identifier
Link Types		Not available yet, but planned
Approvals		Not available yet, but planned
Comments		Not directly queryable. A full text query (oslc_cm:searchTerms) can be used instead

*=This includes the multivalued types (e.g. Contributor lists)

Examples

dc:title="*adoption*"

Work Items created in the last 24 hours

dc:created>"{-24h}"

Work Items that I am subscribed to

rtc_cm:subscribers="{currentUser}"

Work Items tagged with 'tvt' or 'mustfix'

dc:subject in ["tvt","mustfix"]

Major defects

dc:type="defect" and oslc_cm:severity="4"

Work Items in category 'X' ordered by Id

rtc_cm:filedAgainst="https://localhost:9443/jazz/resource/itemOid/com.ibm.team.workitem.Category/_hDbz8EqVEd6HXO10niqZpg" /sort=dc:identifier
rtc_cm:filedAgainst="_hDbz8EqVEd6HXO10niqZpg" /sort=dc:identifier

Work Items containing 'NPE'

oslc_cm:searchTerms="NPE"

Unresolved Work Items, paginated in chunks of 10, only summary and ID

rtc_cm:state="{closed}"
https://localhost:9443/jazz/oslc/contexts/_9BHm0EqVEd6HXO10niqZpg/workitems
?oslc_cm.query=rtc_cm%3Astate%3D%22{closed}%22&oslc_cm.pageSize=10&oslc_cm.properties=dc%3Atitle%2Cdc%3Aidentifier

Using Stored Queries

There is preliminary support in the API for queries created in the Query Editor. They are not exposed in the services descriptors discovery document yet (see Task 86400).

The query collection is exposed at https://localhost:9443/jazz/oslc/queries and is queryable itself. The supported formats are the same as for work item resources. So you can get the queries and the query results in JSON, ATOM, XML, XHTML.

An example in XML:

<rtc_cm:Query rdf:resource="https://localhost:9443/jazz/resource/itemOid/com.ibm.team.workitem.query.QueryDescriptor/_vS4rsF5eEd6EzYK1TPZjDw">
   <dc:identifier/>
   <dc:title>My Query</dc:title>
   <rtc_cm:projectArea rdf:resource="https://localhost:9443/jazz/oslc/projectareas/_9BHm0EqVEd6HXO10niqZpg"/>
   <dc:description/>
   <rtc_cm:results oslc_cm:collref="https://localhost:9443/jazz/oslc/queries/_vS4rsF5eEd6EzYK1TPZjDw/rtc_cm:results"/>
   <dc:creator rdf:resource="https://localhost:9443/jazz/oslc/users/_iTY_8EqVEd6HXO10niqZpg"/>
   <dc:modified>2009-06-21T12:26:26.509Z</dc:modified>
   <rtc_cm:modifiedBy rdf:resource="https://localhost:9443/jazz/oslc/users/_iTY_8EqVEd6HXO10niqZpg"/>
</rtc_cm:Query>

Examples

Get the queries of a user in a specific project area

Query: rtc_cm:projectArea="_gbb_0EqVEd6HXO10niqZpg" and dc:creator="{currentUser}"
URL:   https://localhost:9443/jazz/oslc/queries.xml
?oslc_cm.query=rtc_cm%3AprojectArea%3D%22_gbb_0EqVEd6HXO10niqZpg%22%20and%20dc%3Acreator%3D%22%7BcurrentUser%7D%22

Get the query results as an ATOM feed

The attribute rtc_cm:results points to the query results collection resource, so the query results can be fetched by fetching this resource with the ATOM media type, e.g.

https://localhost:9443/jazz/oslc/queries/_vS4rsF5eEd6EzYK1TPZjDw/rtc_cm:results.atom

Updating Work Items

Roughly outlined, the steps to update a work items are as follows:

• Get a work item representation in JSON or XML
• Modify it by adding, removing or changing values
• Send the modified representation back to the originating URL by using PUT (or PATCH)

Two cases deserve special attention:

Avoid overwriting changes done by someone else: A work item may have changed in the time between fetching it, doing modifications and sending it back. In general, clients should not blindly overwrite the work item contents, but make sure that the changes are applied to the state that they fetched from the server. This is done by including the ETag received on load in the If-Match header when PUTting or PATCHing the work item back to the server. If the state on the server is still the same, the update will succeed with a 200 OK status. If the work item was modified in the meantime, it will fail with a 412 Precondition Failed status.

Partial Updates: While PATCH allows partial updates, PUT generally has the semantics of updating the entire resource (and removing what is not included). In order to allow partial updates via the more generally supported PUT, and in order to selectively remove entire attributes from a work item, you can specify the set of properties to update via the oslc_cm.properties parameter.

Examples

Update a Work Item

First step: Get the work item representation in JSON

URL="https://localhost:9443/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/821"
curl -D - -k  -b $COOKIES -o "wi-821.json" -H "Accept: application/x-oslc-cm-changerequest+json" $URL

This statement writes the HTTP response headers to the console and the JSON content into the file wi-821.json. The headers contain the ETag that we will need when updating the work item:

HTTP/1.1 200 OK
Date: Mon, 15 Jun 2009 14:54:36 GMT
Server: Jetty/5.1.x (Mac OS X/10.5.7 i386 java/1.5.0_16
ETag: "_1am9cFm0Ed6ELJg2MQ68Kg"
Last-Modified: Mon, 15 Jun 2009 14:00:08 GMT
Cache-Control: max-age=0, must-revalidate
Expires: Mon, 15 Jun 2009 14:54:36 GMT
Vary: Accept, Accept-Language
Content-Type: application/x-oslc-cm-changerequest+json;charset=UTF-8
Transfer-Encoding: chunked

For this example, we change the summary, the tags and the severity of the work item:

{
    "dc:title":"test",
    "dc:subject":"",
    "dc:identifier":821,
    "oslc_cm:severity":
    {
        "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gbb_0EqVEd6HXO10niqZpg\/severity\/3"
    },
    ...
    ...
} 

The work item can then be updated using the ETag from the response headers and the modified content:

URL="https://localhost:9443/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/821"
curl -D - -k -b $COOKIES -H "If-Match: _1am9cFm0Ed6ELJg2MQ68Kg" 
-H "Content-Type: application/x-oslc-cm-change-request+json" -H "Accept: application/x-oslc-cm-change-request+json" 
-X PUT --data-binary @wi-821.json $URL

Partial Update of a Work Item

As specified in Partial update of a change request, the properties to be modified need to be included in the PUT request. The following exampe illustrates how to change the type of a work item by sending a partial representation:

File changetype.json:

{
    "dc:type":
    {
        "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/types\/_gbb_0EqVEd6HXO10niqZpg\/task"
    }
}

Shell script snippet to change the work item's type (The If-Match header is omitted for brevity):

URL="https://localhost:9443/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/821?oslc_cm.properties=dc:type"
curl -D - -k -b $COOKIES -H "Content-Type: application/x-oslc-cm-change-request+json" -H "Accept: application/json" 
-X PUT --data-binary @changetype.json $URL

Alternatively, you could use PATCH without the oslc_cm.properties parameter. Note that this works only for the alternative work item URLs like /jazz/oslc/workitems/{id}, but not for the Location based ones:

URL="https://localhost:9443/jazz/oslc/workitems/821"
curl -D - -k -b $COOKIES -H "Content-Type: application/x-oslc-cm-change-request+json" -H "Accept: application/json" 
-X PATCH --data-binary @changetype.json $URL

Adding Links to a Work Item

Links can be added and removed like any other value of a multi-valued attribute by updating a work item with the modified representation. To simplify the case of adding new links, there is a second option. Links can be created by posting their representation to the URL of the attribute specific link collection. These URLs can be discovered by using the collref attribute of a 'link attribute' element. The 'Related Change Management' C/ALM link for instance is represented in XML as:

<oslc_cm:ChangeRequest xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" ...>
   ...
   <oslc_cm:relatedChangeManagement 
            oslc_cm:collref="https://localhost:9443/jazz/oslc/workitems/821/oslc_cm:relatedChangeManagement"/>
   ...
</oslc_cm:ChangeRequest>

Representations of a link:

{
  "rdf:resource":"https:\/\/example.org\/changerequests\/10253",
  "oslc_cm:label":"Task 10253"
}

These representations can be POSTed to the link collections. Assuming that the file link.json contains the JSON snippet above, then a new 'Related Change Management' link can be created using the following shell script:

URL="https://localhost:9443/jazz/oslc/workitems/821/oslc_cm:relatedChangeManagement"
curl -D - -k -b $COOKIES -H "Content-Type: application/x-oslc-cm-change-request+json" -H "Accept: text/json" 
-X POST --data-binary @link.json $URL

It is also possible to create many links at once, by POSTing an array of link representations, e.g.

[
  {
    "rdf:resource":"https:\/\/example.org\/changerequests\/10254",
    "oslc_cm:label":"Task 10254"
  },
  {
    "rdf:resource":"https:\/\/example.org\/changerequests\/10255",
    "oslc_cm:label":"Task 10255"
  },
  {
    "rdf:resource":"https:\/\/example.org\/changerequests\/10256",
    "oslc_cm:label":"Task 10256"
  }
]

Removing Links from a Work Item

This is done by a regular update: Remove the links from the work item representation and PUT/PATCH it back.

Adding a Comment to a Work Item

A comment can be added to a work item by posting a comment representation (JSON or XML) to the comments collection of a work item. The URL of this collection is available from the collref attribute of the comments element of a work item's XML representation:

<oslc_cm:ChangeRequest>
   ...
   <dc:identifier>821</dc:identifier>
   <rtc_cm:comments oslc_cm:collref="https://localhost:9443/jazz/oslc/workitems/821/rtc_cm:comments"/>
   ...
</oslc_cm:ChangeRequest>

Because the comments are exposed directly as an array in JSON, this meta information is not available there.

Representations of a comment:

    {
        "dc:created":"2009-06-12T13:11:29.331Z",
        "dc:creator":
        {
            "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/users\/_iTY_8EqVEd6HXO10niqZpg"
        },
        "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/workitems\/821\/rtc_cm:comments\/0",
        "dc:description":"A new comment"
    }

As the creation date and the creator are automatically assigned, it is sufficient to post the description:

{
   "dc:description":"My new comment"
}

Assuming that this JSON snippet is in a file called comment.json, the following shell script adds the comment to work item 821:

URL="https://localhost:9443/jazz/oslc/workitems/821/rtc_cm:comments"
curl -D - -k -b $COOKIES -H "Content-Type: application/x-oslc-cm-change-request+json" -H "Accept: text/json" 
-X POST --data-binary @comment.json $URL

Removing a Custom Attribute from a Work Item

Only custom attributes can be removed from a work item. An attempt to remove a built-in attribute will be ignored. The removal is done with a partial update request that specifies the attribute in the oslc_cm.properties list but doesn't include the attribute in the representation.

Adding a Custom Attribute to a Work Item

Custom attributes can be added to a work item by including it in the representation for the update request. The attribute itself must exist in the repository already or a 409 Conflict status will be returned.

Creating Work Items

Work Items are created by POSTing their (partial) XML or JSON representation to the factory URL from the service descriptors document:

<oslc_cm:factory oslc_cm:default="true">
   <dc:title>Default location for creation of change requests</dc:title>
   <oslc_cm:url>https://localhost:9443/jazz/oslc/contexts/_9BHm0EqVEd6HXO10niqZpg/workitems</oslc_cm:url>
</oslc_cm:factory>

A work item representation for the creation case might look like this (in a file called create-simple.json):

{
    "dc:title":"My first new work item",
    "dc:description":"A description for the new work item",
    "dc:type":
    {
        "rdf:resource":"https:\/\/publicuri.test.org:9443\/jazz\/oslc\/types\/_9BHm0EqVEd6HXO10niqZpg\/defect"
    },
    "rtc_cm:filedAgainst":
    {
        "rdf:resource":"https:\/\/publicuri.test.org:9443\/jazz\/resource\/itemOid\/
                        com.ibm.team.workitem.Category\/_-hBTUEqVEd6HXO10niqZpg"
    }
}

As an example, this representation can be POSTed to the factory URL using the following shell script:

URL="https://localhost:9443/jazz/oslc/contexts/_9BHm0EqVEd6HXO10niqZpg/workitems"
curl -D - -k -b $COOKIES -H "Content-Type: application/x-oslc-cm-change-request+json" -H "Accept: text/json" 
-X POST --data-binary @create-simple.json $URL

On successful creation, the server will answer with a '201 Created' status code and a Location header that contains the URL of the newly created resource. The full representation (or whatever was specified with oslc_cm.properties) will be returned as well.

Creating Draft Work Items

Creating new work items without knowing which attributes are required is likely to break over time, e.g. when new required attributes are introduced. For this case and also for the case where a work item needs only be primed with some initial values but then shown to the user in the Web UI, work item drafts were introduced. Creating a draft works exactly the same as creating a regular work item, but is not susceptible to missing required attributes.

The factory URL for draft work items is also available from the service descriptors document:

<oslc_cm:factory calm:id="drafts">
   <dc:title>Location for creation of draft change requests</dc:title>
   <oslc_cm:url>https://localhost:9443/jazz/oslc/contexts/_9BHm0EqVEd6HXO10niqZpg/drafts/workitems</oslc_cm:url>
</oslc_cm:factory>

Upon creation, the Location header contains the URL of the draft work item. This URL can e.g. be opened in the browser and allows a user to edit the draft work item. It will turn into a regular work item when the user saves the work item.

Appendix A

This section list some useful resources that may help you getting started using the API.

Form based authentication using curl

For small command line based tools, a shell script using curl to interact with the RTC repository is often sufficient. The two common authentication options for an RTC repository setup are either Basic Auth or Form Based Auth. While Basic Auth is commonly supported by HTTP clients, Form Based Auth can be a bit trickier.

Accessing work item 1 on a server configured for Form Based Auth can be done using this shell script:

COOKIES=./cookies.txt
USER=username
PASSWORD=password
HOST="https://localhost:9443/jazz"
curl -k -c $COOKIES "$HOST/authenticated/identity"
curl -k -L -b $COOKIES -c $COOKIES -d j_username=$USER -d j_password=$PASSWORD "$HOST/authenticated/j_security_check"
# If this line returns the JSON representation of work item 1, authentication was successful
#curl -k -b $COOKIES "$HOST/oslc/workitems/1.json"

The login process (the first two curl commands in the above example) is necessary only once per session. Any subsequent call can be made using -b $COOKIES. The option -k is only necessary when the server has a self-signed or expired certificate.

Basic authentication using curl

Using curl with a server configured for Basic Auth is straightforward. E.g. work item 1 can be accessed on the command line as:

curl -k -u username:password "https://localhost:9443/oslc/workitems/1.json"

To use all the script examples in this document with Basic Auth,
you would typically replace -b $COOKIES with -u <user:password>.