In this scenario the client wishes to add a new property to an architecture resource.
The client first GET’s the OSLC AM representation of the AM resource. It must read in the entire resource and get the ETag value from the response header.
It inserts a new XML element as a child of the <oslc_am:Resource> element with the property. The client must then PUT back the entire contents of the resource to the provider (with the new property).
The service provider will notice the new element and interpret it as a new property to of the resource. The removal of editable elements in the document imply the deletion of that property.
There is no garantee that all service providers will allow clients to add resource properties, or such operations require certain priviledges on the user. When the server does not permit the modification of a resource it will return a 403 Prohibited response. If the ETag is out of sync a 409 Conflict is returned. Clients should be prepared to accept any valid HTTP status code.
Example 1. Insert a simple custom property
This scenario assumes that the service provider allows the insertion of links, and that the client user has the permissions to do so. The client has a URI reference to an AM resource ( https://am.acme.com/resources/res323), and a URI of the externally managed requirement resource ( https://reqserver.acme.com/requirements/req10). The client also knows what link type (predicate) to use ( http://acme.com/links/elaborates). The client could allow the user to select the link type from a list of known types on the AM service provider using the Link Type service.
1. The client GET’s the AM resource to insert a link into, and notes the ETag value.
Request
GET https://am.acme.com/resources/res323
Accept: application/x-oslc-am-resource+xml
Response
200 OK
Content-Type: application/x-oslc-am-resource+xml
ETag: "_siemvnshyu2746sakalfuy"
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/"
rdf:about="https://acme.com/resources/res1">
<oslc_am:Resource>
<dc:title>ServiceInterface</dc:title>
<dc:description>This interface is used to do service things.</dc:description>
<dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
<dc:format>application/x-uml+xml</dc:format>
</oslc_am:resource>
</rdf:RDF>
- The client modifies the content, inserting a new element into the body of the <oslc_am:Resource> to represent the link. The client then PUTs back the resource to the same URI with the current ETag value in the If-Match header. If the service provider permits the the insertion of link, the user has authorization, the syntax of the link is correct, the service provider will response with a 200 OK response.
Request
PUT https://am.acme.com/resources/res323
Content-Type: application/x-oslc-am-resource+xml
If-Match: "_siemvnshyu2746sakalfuy"
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/"
xmlns:acme=" =http://acme.com/links/">
<rdf:Description rdf:about="https://acme.com/resources/res1">
<dc:title>ServiceInterface</dc:title>
<dc:description>This interface is used to do service things.</dc:description>
<dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
<dc:format>application/x-uml+xml</dc:format>
<acme:priority>HIGH</acme:priority>
</rdf:Description>
</rdf:RDF>
Response
200 OK
ETag: "_sownmds21sa92js6aloaa"
Example 2. User doesn’t have rights to add property
This scenario shows how a provider will respond to a client request to insert a custom property, when the user does not have rights to such an action, or the server does not permit it.
1. The client GET’s the AM resource to insert a link into, and notes the ETag value.
Request
GET https://am.acme.com/resources/res323
Accept: application/x-oslc-am-resource+xml
Response
200 OK
Content-Type: application/x-oslc-am-resource+xml
ETag: "_siemvnshyu2746sakalfuy"
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/">
<rdf:Description rdf:about="https://acme.com/resources/res1">
<dc:title>ServiceInterface</dc:title>
<dc:description>This interface is used to do service things.</dc:description>
<dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
<dc:format>application/x-uml+xml</dc:format>
</rdf:Description>
</rdf:RDF>
2. The client modifies the content, inserting a new element into the body of the <oslc_am:Resource> to represent the property.
The client then PUTs back the resource to the same URI with the current ETag value in the If-Match header. The server responds with a 403 and indicates the reason in the body.
Request
PUT https://am.acme.com/resources/res323
Content-Type: application/x-oslc-am-resource+xml
If-Match: "_siemvnshyu2746sakalfuy"
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/"
xmlns:acme="http://acme.com/links/"
xml:base="https://acme.com/resources/res1">
<df:Description rdf:about="https://acme.com/resources/res1">
<dc:title>ServiceInterface</dc:title>
<dc:description>This interface is used to do service things.</dc:description>
<dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
<dc:format>application/x-uml+xml</dc:format>
<acme:priority>HIGH</acme:priority>
</df:Description>
</rdf:RDF>
Response
403 Forbidden
Content-Type: application/rdf+xml
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:oslc="http://open-services.net/xmlns/common/1.0/">
<oslc:Error>
<oslc:statusCode>403</oslc:statusCode>
<oslc:message> The user does not have the priviledges to update resources.</oslc:message>
</oslc:Error>
</rdf:RDF>
