Architecture Management Service Description
Introduction
This document describes how clients can discover services that the service provider offers. It leverages the common service provider
catalog specification. This document specifies the actual AM
service document, which the catalog document points to.
This specification leverages the common
OSLC specification for service description. This document defines the structure of the catalog of of services. A service provider catalog contains references to a number of services, often organized by project hosted on the service provider (but not necessarily). Each of these service providers specifies a
details URL and a
services URL. The details URL can be navigated to by a browser to view general information about this services provider (i.e. the default home page for the project that these services are being provided for). The services URL returns a service document that includes the factory or creation URLs and resource picker URLs.
Sevice Discovery
Starting with a single entry point to a service provider
{base-url}
, clients will discover the (typically hierarchical) arrangement of contexts (which may be development projects) managed by the application. To support the wide range of application and project configurations, OSLC is not specifying a predetermined arrangement of these contexts. Instead, clients will be able to iterate through a group of collections (Service Provider Catalogs) until identifying a context of interest, where the client will find an AM Service Description Document.
The dicovery model flow is as follows:
- Request information from an OSLC AM service provider:
GET {url}
- If Response is a Service Provider Catalog:
- An entry is selected from the Service Provider Catalog
- With this entry's
{url}
, repeat to step #1
- If Response is a Service Description Document, then continue to next step
- Configuration has completed
The number of iterations over the configuration choices should be set by the client application. Typical configurations should not need more than 2 levels of configuration context, so a limit of 5 is recommended.
Termination of the discover occurs when a the client application receives an HTTP response with a Content-Type of
application/x-oslc-service-description+xml
and the service description document as the response's content body.
XML namespace abbreviations used in this resource document:
-
rdf
- RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
-
dc
- The Dublin Core Metadata Terms namespace - http://purl.org/dc/terms/
-
oslc_disc
- The Open Services for Lifecycle Collaboration Discovery namespace - http://open-services.net/xmlns/discovery/1.0/
Example
A Service Provider Catalog Resource located at
http://am.acme.com/AMCatalog
. The document lists 2 service providers.
<?xml version="1.0"?>
<oslc_disc:ServiceProviderCatalog
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
rdf:about="http://am.acme.com/AMCatalog" >
<dc:title>Architecture Management Service Provider Catalog</dc:title>
<oslc_disc:entry>
<oslc_disc:ServiceProvider>
<dc:title>Project X</dc:title>
<oslc_disc:details rdf:resource="http://am.acme.com/projects/_CGwYgAnrEd6_yLxvteIpZw" />
<oslc_disc:services
rdf:resource="http://am.acme.com/projects/_CGwYgAnrEd6_yLxvteIpZw/services.xml" />
</oslc_disc:ServiceProvider>
</oslc_disc:entry>
<oslc_disc:entry>
<oslc_disc:ServiceProvider>
<dc:title>Project Y</dc:title>
<oslc_disc:details rdf:resource="http://am.acme.com/projects/_sajkASDo92asDAsjd" />
<oslc_disc:services
rdf:resource="http://am.acme.com/projects/_sajkASDo92asDAsjd/services.xml" />
</oslc_disc:ServiceProvider>
</oslc_disc:entry>
</oslc_disc:ServiceProviderCatalog>
AM Service Description Resource
A Service Description Resource is an informational resource describing a the contextual configuration needs of a service provider. It provides configuration definitions needed by consumers of an AM service provider.
The Service Description Document MUST be indentified using the media type of
application/x-oslc-service-description+xml
.
XML namespace abbreviations used in this resource document:
-
rdf
- RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
-
dc
- The Dublin Core Metadata Terms namespace - http://purl.org/dc/terms/
-
oslc_am
- The Open Services for Lifecycle Collaboration Architecture Management namespace - http://open-services.net/xmlns/am/1.0/
The Service Descriptor element provides human readable information about the context for which the services are for. A human readable label for the context that these services are for is specified in the text content of a child dc:title element. A longer description is specified in the optional text content of a child dc:description element.
A Service Descriptor element includes many
oslc_am:SelectionDialog
and
oslc_am:ResourceFactory
child elements.
Selection Dialog elements MUST specify the URL of the service with a
rdf:resource
attribute. This is the URL which clients
GET
the HTML based UI for the selection (and if supported, creation) of AM Resources in this context. The REST services provided at this URL are defined in
AM Delegated Resource Selection and Creation REST API . The required
dc:title
child element provides a human readable label for this service. Two optional child elements;
oslc_am:hintWidth
and
oslc_am:hintHeight
specify the suggested size of the dialog or frame to render the HTML content in. Expected for the size values are defined by
CSS length units.
Resource Factory elements MUST specify the URL of the service with a
rdf:resource
attribute. This is the URL that clients
POST
new AM Resources to. The optional
dc:title
provides a human readable label of this factory service.The REST services provided at this URL are defined in
AM Resource Factory REST API.
Example
In this example the service description is for a context called "Project X". The services provided are a
Resource Picker and an
AMR Factory.
<oslc_am:ServiceDescriptor 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="http://am.acme.com/service-descriptor.xml">
<dc:title>Project X</dc:title>
<dc:description>My description of Project X.</dc:description>
<oslc_am:ResourceFactory
rdf:resource="https://am.acme.com/resourceFactory?projectId=Project%20X">
<dc:title>Factory for creating AM Resources from an OSLC AM resource format in Project X</dc:title>
</oslc_am:ResourceFactory>
<oslc_am:ResourceSourceFactory
rdf:resource="https://am.acme.com/resourceFactory?projectId=Project%20X">
<dc:title>Factory for creating AM Resources from non-OSLC AM resource formats in Project X</dc:title>
</oslc_am:ResourceSourceFactory>
<oslc_am:SimpleQuery
rdf:resource="https://am.acme.com/simplequery/project1/">
<dc:title>Simple Query end point</dc:title>
</oslc_am:SimpleQuery>
<oslc_am:LinkTypeFactory
rdf:resource="https://am.acme.com/linkTypeFactory?projectId=Project%20X">
<dc:title>Factory for getting creating (POST) Link Type URIs for use in Project X</dc:title>
</oslc_am:LinkTypeFactory>
<oslc_am:LinkTypeQuery
rdf:resource="https://am.acme.com/linkTypeFactory?projectId=Project%20X">
<dc:title>Factory for getting Link Type URIs for use in Project X</dc:title>
</oslc_am:LinkTypeQuery>
<oslc_am:SelectionDialog
rdf:resource="https://am.acme.com/resourcePicker?projectId=Project%20X">
<dc:title>Web UI for finding and selecting AM resources in Project X</dc:title>
<oslc_am:hintWidth>400px</oslc_am:hintWidth>
<oslc_am:hintHeight>500px</oslc_am:hintHeight>
</oslc_am:SelectionDialog>
</oslc_am:ServiceDescriptor>
Providers of this Service Description Document MAY provide additional properties in a non-OSLC namespace.