This specification defines the OSLC Architecture Management domain, a RESTful web services interface for the management of architectural resources and relationships between those and related resources such as product change requests, activities, tasks, requirements or test cases. To support these scenarios, this specification defines a set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, as well as HTTP response codes, content type handling and resource formats.
This specification defines a RESTful web services interface for the Architecture Management (AM) domain. This domain addresses the management of product design artifacts including models, and relationships with other resources such as requirements, testing resources and change requests. To support these scenarios, this specification defines a set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response codes, content type handling and resource formats..
The intent of this specification is to define the capabilities needed to support integration scenarios defined by the Architecture Management working group and not to provide a comprehensive interface to Architecture Management. The resource formats and operations may not match exactly the native artifacts supported by architecture management AM Servers but are intended to be compatible with them. The approach to supporting these scenarios is to delegate operations, as driven by service provider contributed user interfaces, as much as possible and not require a service provider to expose its complete data model and application logic.
This specification is a [[!OSLCCore3]] compliant specification, and as such most of its content are references to [[!OSLCCore3]].
The following sub-sections define the mandatory and optional requirements for an OSLC Architecture Management (OSLC AM) server.
This specification is based on [[!OSLCCore3]]. OSLC AM servers MUST be compliant with both the core specification, MUST follow all the mandatory requirements in the normative sections of this specification, and SHOULD follow all the guidelines and recommendations in both these specifications.
An OSLC AM server MUST implement the domain vocabulary defined in OSLC Architecture Management Version 2.1. Part 2: Vocabulary
The following table summarizes the requirements from OSLC Core Specification as well as some additional requirements specific to the AM domain. Note that this specification further restricts some of the requirements from the OSLC Core Specification. See the previous sections in this specification or the OSLC Core Specification to get further details on each of these requirements.
Requirement | Meaning |
---|---|
Absolute URIs | AM Servers MUST use absolute URIs for all references to resources by properties |
Unknown properties and content | AM Servers MAY ignore unknown content and AM clients MUST preserve unknown content. AM Servers MAY discard such properties and continue the POST or PUT operation without warning to the client. |
Resource Operations | AM Servers MUST support resource operations via standard HTTP operations |
Update and Delete | AM Servers SHOULD support resource modifications with standard HTTP PUT and DELETE methods. AM Servers MAY limit modifications |
HTTP If-Match use | AM Servers supporting update and delete of resources MUST support the standard HTTP If-Match header in PUT and DELETE for concurrency protection of resources. |
Resource Paging | AM Servers MAY provide paging for resources but only when specifically requested by clients |
Partial Resource Representations | AM Servers MAY support requests for a subset of a resource's properties via the oslc.properties URL parameter retrieval via HTTP GET |
Partial Update | AM Servers MAY support partial update of resources via the oslc.properties URL parameter retrieval via HTTP PUT and or using [[LDPPatch]]. |
Discovery | AM Servers MAY provide a Service Provider Catalog, MUST provide a Service Provider resource, and MAY provide other forms of discovery described in [[!OSLCCore3]]. |
Creation Factories | AM Servers MAY provide creation factories for resource formats that it supports. AM Servers MAY support creation factories for OSLC AM defined resources formatted as application/rdf+xml. AM Servers MAY support creation factories for other formats, and indicate such creation factories with a non-default identifier in the oslc:usage property of the creation factory definition in the service provider document |
Query Capabilities | AM Servers MUST provide query capabilities on oslc_am:Resource resources to enable clients to query for resources. AM Servers SHOULD support a query interface for oslc_am:LinkType resources that support a GET for all LinkType resources. Such a GET does not require any simple query syntax parameters. AM Servers MAY support the full query syntax for LinkType resources. |
Query Syntax | OSLC query capabilities MUST support the OSLC Core Query Syntax |
Delegated Dialogs | AM Services SHOULD offer selection delegated dialogs and MAY offer creation delegated dialogs specified via service provider resource |
Resource Preview | AM Services SHOULD offer resource previews for resources that may be referenced by other resources |
Authentication | AM Services SHOULD follow the recommendations for Authentication specified in [[!OSLCCore3]] |
Error Responses | AM Servers SHOULD provide error responses using OSLC Core defined error formats |
RDF/XML Representations | AM Servers MUST support RDF/XML representations for OSLC Defined Resources |
XML Representations | AM Servers MUST support XML representations that conform to the OSLC Core Guidelines for XML |
JSON Representations | AM Servers MAY support JSON representations; those which do MUST conform to the OSLC Core Guidelines for JSON |
HTML Representations | AM Servers MAY provide HTML representations for GET requests |
This specification follows the specification version guidelines given in [[!OSLCCore3]].
In addition to the namespace URIs and namespace prefixes oslc
, rdf
,
dcterms
and foaf
defined in [[!OSLCCore3]], OSLC AM defines the namespace URI of
http://open-services.net/ns/am#
with a preferred namespace prefix of oslc_am
.
In addition to the requirements for resource representations in [[!OSLCCore3]], this section outlines further refinements and restrictions.
For HTTP GET/PUT/POST requests on all OSLC AM and OSLC Core defined resource types,
application/rdf+xml
. AM Clients
SHOULD be prepared to deal with any valid RDF/XML document.
application/xml
. The XML
representations MUST follow the guidelines outlined in the
OSLC Core Representations Guidance
to maintain compatibility with [[!OSLCCore2]].
application/json
. The JSON
representations MUST follow the guidelines outlined in the
OSLC Core Representations Guidance
to maintain compatibility with [[!OSLCCore2]].
For compatibility with OSLC 2.0, OSLC AM Servers MAY accept the OSLC Core Version header (OSLC-Core-Version: 2.0) in any HTTP request as specified in [[!OSLCCore3]], and return an OSLC AM 2.0 representation (including the OSLC-Core-Version: 2.0 header). If the OSLC Core Version header is absent on a request, or has some undefined value, the OSLC AM Server MUST return an AM 3.0 representation.
Since OSLC 3.0 is a compatible superset of OSLC 2.0, an AM 3.0 representation may also be an AM 2.0 representation, even if the OSLC Core Version header is absent.
OSLC AM Servers MUST support HTTP GET requests on Architecture Management Resources (AMR), with an Accept
header of application/rdf+xml
, and return the RDF/XML representation of the resource.
OSLC AM Servers SHOULD support HTTP GET requests on Architecture Management Resources (AMR), with an Accept
header of an HTML type ( application/html
, application/xhtml
), and return either an
HTML/XHTML representation of the resource or redirect the client to another URL that can (i.e. 302 Redirect).
OSLC AM Servers SHOULD support HTTP GET requests for user interface (UI) preview of Architecture Management Resources (AMR) as defined by [[!OSLCPreview]].
OSLC AM Servers SHOULD support resource modifications on Architecture Management Resources (AMR) with standard HTTP PUT and DELETE methods. AM Servers MAY limit modifications in any way they want. For example a service provider may limit updates to resources to simple link properties of link types already defined in the provider. Modification methods MUST use the If-Match header for concurrency management. Providers MAY discard such properties and continue a PUT operation without warning to the client.
OSLC AM Servers SHOULD support resource modifications on LinkType Resources (LTR) with standard HTTP PUT and DELETE methods. AM Servers MAY limit modifications in any way they want. For example a service provider may not support additional properties. Modification methods SHOULD use the If-Match header for concurrency management.
See [[!OSLCCore3]], OSLC AM puts no additional constraints on authentication.
See [[!OSLCCore3]], OSLC AM puts no additional constraints on error responses
OSLC AM Servers SHOULD support pagination of query results and MAY support pagination of a single resource's properties as defined by [[!OSLCCore3]].
An OSLC AM server MAY support the oslc.properties
URL query parameter on an HTTP GET request on
individual resource request or a collection of resources by query. If the oslc.properties
query
parameter is omitted on the request, then all resource properties MUST be provided in the response.
An OSLC AM client MAY request that a subset of a resource's properties be updated by identifying those
properties to be modified using the oslc.properties
URL parameter on a HTTP PUT request.
An OSLC AM Server MAY support updating a subset of a resource's properties by using the [[LDPPatch]]
PATCH
method.
For compatibility with [[!OSLCCore2]], an AM Server MAY also support partial update by identifying those
properties to be modified using the oslc.properties
URL parameter on a HTTP PUT request.
If the parameter oslc.properties
contains a valid resource property on the request that is not
provided in the content, the server MUST set the resource's property to a null or empty value. If the
parameter oslc.properties
contains an invalid resource property, then a
409 Conflict
MUST be returned.
OSLC Architecture Management Resources 2.1 Defines the vocabulary terms and constraints for OSLC Change Management resources. These terms and constraints are specified according to [[!OSLCCore3]].
OSLC AM servers SHOULD support Resource Shapes as defined in [[!OSLCShapes]].
OSLC AM Servers MUST provide a ServiceProvider Resource that can be retrieved at a implementation dependent URI.
OSLC AM Servers MUST provide a ServiceProviderCatalog Resource that can be retrieved at a implementation dependent URI.
OSLC AM Servers MUST provide an oslc:serviceProvider
property for their defined resources that
will be the URI to a ServiceProvider Resource. This does not prevent AM Servers from providing multiple servie
provider properties with different values, if the service provider supports multiple OSLC domain
specifications, and the resource is applicable to multiple domains.
OSLC AM Servers MUST supply a value of http://open-services.net/ns/am#
for the property
oslc:domain
on either oslc:ServiceProvider
or
oslc:ServiceProviderCatalog
resources.
OSLC AM Servers MAY support CreationFactories as defined by [[!OSLCCore3]].
OSLC AM Servers MAY discard properties it does not recognize and continue the POST operation without warning to the client. The returned resource will contain the accepted properties (and server generated properties like the dcterms:identifer) so clients will be able to confirm if required what was accepted.
If OSLC AM Servers support the creation of resources from the OSLC defined
oslc_am:Resource
format, there MUST be at least one Creation Factory entry in the Services
definition, and its oslc:usage
property MUST be set to
http://open-services/ns/core#default
. The oslc:resourceType
MUST be set to
http://open-services.net/ns/am#Resource
.
If OSLC AM Servers support the creation of resources from a resource other than oslc_am:Resource
,
there MUST be a separate creation services definition whose oslc:usage
property MUST NOT be set
to http://open-services/ns/core#default
.
OSLC AM Servers SHOULD support the Query Capabilities as defined by [[!OSLCCore3]] for both
oslc_am:Resource
and oslc_am:LinkType
resources.
If the service provider supports query capability for oslc_am:Resource
resources, it MUST support
the following query parameters:
oslc.where
oslc.searchTerms
OSLC AM Servers SHOULD support query capability for oslc_am:LinkType
resources. If supported then
AM Servers MUST support a simple GET without any query parameters that returns all link type resources. AM
Servers SHOULD support the full OSLC query syntax.
OSLC AM Servers SHOULD support the selection of resources by delegated selection dialogs as defined by [[!OSLCCore3]].
OSLC AM Servers MAY support the creation of resources by delegated creation dialogs as defined by [[!OSLCCore3]].
In oslc:Dialog
elements, the two optional child elements; oslc:hintWidth
and
oslc:hintHeight
specify the suggested size of the dialog or frame to render the HTML content in.
Expected size values are defined by CSS length units.
The following individuals have participated in the creation of this specification and are gratefully acknowledged:
Participants:
James Amsden, IBM (Editor)
Chris Armstrong, Armstrong Process Group
Andy Berner, IBM
Scott Bosworth, IBM
Jim Conallen, IBM
Derry Davis, Accenture
Brenda Ellis, Northrop Grumman Corporation
Ian Green, IBM
Jonathan Harclerode, Accenture
Simon Helsen, IBM
Clyde Icuspit, IBM
Wally Mclaughlin, Armstrong Process Group
Thomas Picolli, IBM
Vishy Ramaswamy, IBM
Ren Renganathan. Citi Bank
Nick Crossley, IBM