Navigation:
Documentation
Archive



Page Tree:

Child pages
  • Service Catalog Service Contract Description v0.8 - BDOC

This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.

Skip to end of metadata
Go to start of metadata

Contract:

 

 

Unknown macro: {multi-excerpt} Service Catalog

 

 

Service

 

Brief description

The Service Catalog service provides information about the services offered by the Bamboo Service Platform. Based on this information, service consumers can see what functionality a service provides and how, select which service provider best meets their needs, and invoke the service.

Version

This page describes the Service Catalog service API, v. 0.8

This service can be used to discover the version and other metadata about deployed service code that fulfills this API.

Overview and Definitions

The Service Catalog service provides a service consumer (e.g. end user, application developer) with access to information about available services developed for use in, and deployed through, the Bamboo Service Platform (BSP). This information includes both a reference to description of the service's RESTful API (i.e. a contract that specifies how the service will perform internet-based HTTP GET, POST, PUT, and DELETE calls); as well as a profile of the service, listing all service providers and any supporting services that are potentially involved in implementing the functionality specified by the service. Using the Service Catalog service, a service consumer interested in some set of functionality can:

  • Obtain information about what services are currently available
  • What functionality a service provides and how
  • How to invoke a service over the internet
  • Select from among multiple candidate service providers for a service; service providers are differentiated by the organization that developed the service provider, and by the version of the service a service provider supports.

A Service Profile describes the functionality provided by a single service, as well as information about the service providers that it calls in the course of delivering that functionality.

A Service Profiles list is an XML document that, for each available service, includes a link to the service's Service Description, and a summary version of its Service Profile.

Data available via the Service Catalog service is supplied by service developers. For a fuller understanding of the information in a Service Profile, please refer to the Service Catalog Service Description and Assumptions page of Project Bamboo's development wiki.

Assumptions

For assumptions implicit in this service's functionality, visit the Service Catalog Service Description and Assumptions page of Project Bamboo's development wiki.

References

Known Issues

None

ROA Layer API

RESTful service methods performing Read and List functions over Service Profiles.

Base URLs

Currently available instances of the Bamboo Services Platform are INSECURE, are operated with NO EXPLICIT SLA, and should be considered STATELESS: that is, data may be wiped from persistent stores at any time.

A secure instances of the BSP, with URLs that do not require explicit inclusion of a port number, and for which data will be preserved on future upgrades is anticipated in Fall 2012.

Currently available base URLs:

To receive notices about maintenance, down-time, and other issues about instances of the Bamboo Services Platform you may subscribe to bsp-bulletins@lists.projectbamboo.org. You may unsubscribe here.

Schema

Service Profile

A Service Profile describes the functionality provided by a single service, as well as information about the service providers that it calls in the course of delivering that functionality.

Read a Service Profile

A client requests a service's profile by submitting the service's unique identifier (i.e. spid).

Calling Method and Arguments

Invoked as an HTTP GET method. Send an HTTP request of the form:

GET /bsp/serviceprofiles/spid HTTP/1.1

Parameter

Meaning

spid

The unique identifier for a Service Profile

Accept Header

application/xml

Response

On success, a response with a "200 OK" HTTP status code will be returned.

Parameter

Meaning

HTTP Body

An instance of a ServiceProfile XML document

Example ServiceProfile XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sc:serviceProfile
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:dc="http://purl.org/dc/elements/1.1/"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:foaf="http://xmlns.com/foaf/0.1/"
    xmlns:bsp="http://projectbamboo.org/bsp/resource"
    xmlns:sc="http://projectbamboo.org/bsp/services/core/servicecatalog/domain/serviceprofile"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    rdf:about="http://localhost/bsp/serviceprofiles/urn:uuid:813f76f4-cc4b-44d8-ad36-81810e0356d7">
    <sc:servicePId>urn:uuid:813f76f4-cc4b-44d8-ad36-81810e0356d7</sc:servicePId>
    <sc:name>Service Catalog Service</sc:name>
    <sc:version>1.0.0</sc:version>
    <sc:objectClass>org.projectbamboo.bsp.services.core.servicecatalog.resources.ServiceProfiles</sc:objectClass>
    <sc:serviceDescription>Provides information about the services offered by the Bamboo Service Platform</sc:serviceDescription>
    <sc:serviceDescriptionLocation>https://wiki.projectbamboo.org/display/BTECH/Service+Catalog+Service+Home</sc:serviceDescriptionLocation>
    <sc:serviceVendor>UC Berkeley</sc:serviceVendor>
    <sc:serviceRestfulAddress>http://localhost/bsp/serviceprofiles</sc:serviceRestfulAddress>
    <sc:serviceProviders>
        <sc:name>Service Profile Document Handler Service</sc:name>
        <sc:defaultServiceProvider>true</sc:defaultServiceProvider>
        <sc:serviceProviderSupportedVersionsRange>[1.0.0,2.0.0)</sc:serviceProviderSupportedVersionsRange>
        <sc:serviceProviderDetails>
            <sc:serviceRanking>1</sc:serviceRanking>
            <sc:serviceProviderType>functional</sc:serviceProviderType>
            <sc:serviceProviderContact>falvarez@berkeley.edu</sc:serviceProviderContact>
            <sc:metadata sc:key="defaultServiceProvider">true</sc:metadata>
            <sc:metadata sc:key="org.springframework.osgi.bean.name">serviceProfileDocumentHandler</sc:metadata>
            <sc:metadata sc:key="service.id">449</sc:metadata>
            <sc:metadata sc:key="Bundle-SymbolicName">org.projectbamboo.bsp.servicecatalog.service</sc:metadata>
            <sc:metadata sc:key="Bundle-Version">0.8.0.-SNAPSHOT</sc:metadata>
        </sc:serviceProviderDetails>
    </sc:serviceProviders>
    <sc:servicesUsed>
        <sc:servicePId>urn:uuid:813f76f4-bc4b-44d8-ad36-81810f0356d7</sc:servicePId>
        <sc:name>Service Catalog</sc:name>
        <sc:version>1.0.0</sc:version>
        <sc:objectClass>org.projectbamboo.bsp.services.core.servicecatalog.service.ServiceCatalogService</sc:objectClass>
        <sc:serviceDescription>Provides access to service providers</sc:serviceDescription>
        <sc:serviceDescriptionLocation>https://wiki.projectbamboo.org/display/BTECH/Service+Catalog+Service+Description+and+Assumptions</sc:serviceDescriptionLocation>
        <sc:serviceVendor>UC Berkeley</sc:serviceVendor>
    </sc:servicesUsed>
    <sc:servicesUsed>
        <sc:servicePId>urn:uuid:813f76f4-bc4b-44d8-ad36-81810e0356d9</sc:servicePId>
        <sc:name>Service Profile Document Handler Service</sc:name>
        <sc:version>1.0.0</sc:version>
        <sc:objectClass>org.projectbamboo.bsp.services.core.servicecatalog.service.ServiceProfileDocumentHandlerService</sc:objectClass>
        <sc:serviceDescription>Document marshaling and unmarshaling for the Service Profile resource</sc:serviceDescription>
        <sc:serviceDescriptionLocation>https://wiki.projectbamboo.org/display/BTECH/Document+Handler+Service+Home</sc:serviceDescriptionLocation>
        <sc:serviceVendor>UC Berkeley</sc:serviceVendor>
    </sc:servicesUsed>
</sc:serviceProfile>

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the Get request:

Error (Status Code)

Meaning

Returned When

401

Unauthorized

The resource could not be created because the client submitting the request either has not provided authentication credentials, or authentication failed, or authorization has been refused for those credentials

404

Not Found

The resource requested for reading does not exist

500

Internal Server Error

A service error prevented the resource from being returned

List Service Profiles

A Service Profiles list is an XML document that, for each available service, includes a link to the service's Service Description, and a summary version of its Service Profile.

Calling Method and Arguments

Invoked as an HTTP GET method. Send an HTTP request of the form:

GET [http://services.projectbamboo.org/bsp/serviceprofiles HTTP/1.1

Parameter

Meaning

Accept Header

application/xml

Response

On success, a response with a "200 OK" HTTP status code will be returned.

Parameter

Meaning

HTTP Body

An instance of a serviceProfileList XML document

Example serviceProfileList XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sc:serviceProfileList
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:dc="http://purl.org/dc/elements/1.1/"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:foaf="http://xmlns.com/foaf/0.1/"
    xmlns:bsp="http://projectbamboo.org/bsp/resource"
    xmlns:sc="http://projectbamboo.org/bsp/services/core/servicecatalog/domain/serviceprofile"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <bsp:header>
        <dcterms:created xsi:type="dcterms:W3CDTF">2012-04-27T11:27:20.645-07:00</dcterms:created>
        <dcterms:creator xsi:type="foaf:Agent" rdf:about="serviceprofiles"/>
        <bsp:orderedBy>ascending</bsp:orderedBy>
        <bsp:listLength>1</bsp:listLength>
        <bsp:pageNumber>1</bsp:pageNumber>
        <bsp:pageLength>20</bsp:pageLength>
    </bsp:header>
    <sc:serviceProfile rdf:about="http://localhost/bsp/serviceprofiles/urn:uuid:813f76f4-cc4b-44d8-ad36-81810e0356d7">
        <sc:servicePId>urn:uuid:813f76f4-cc4b-44d8-ad36-81810e0356d7</sc:servicePId>
        <sc:name>Service Catalog Service</sc:name>
        <sc:version>1.0.0</sc:version>
        <sc:serviceDescription>Provides information about the services offered by the Bamboo Service Platform</sc:serviceDescription>
        <sc:serviceDescriptionLocation>https://wiki.projectbamboo.org/display/BTECH/Service+Catalog+Service+Home</sc:serviceDescriptionLocation>
        <sc:serviceVendor>UC Berkeley</sc:serviceVendor>
        <sc:serviceRestfulAddress>http://localhost/bsp/serviceprofiles</sc:serviceRestfulAddress>
        <sc:serviceProviders>
            <sc:name>Service Profile Document Handler Service</sc:name>
            <sc:defaultServiceProvider>false</sc:defaultServiceProvider>
            <sc:serviceProviderSupportedVersionsRange>[1.0.0,2.0.0)</sc:serviceProviderSupportedVersionsRange>
        </sc:serviceProviders>
    </sc:serviceProfile>
</sc:serviceProfileList>

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the Get request:

Error (Status Code)

Meaning

Returned When

401

Unauthorized

The resource could not be created because the client submitting the request either has not provided authentication credentials, or authentication failed, or authorization has been refused for those credentials

500

Internal Server Error

A service error prevented the resource from being returned

SOA Layer API

Link to Javadoc here; or, include note: Javadoc will be linked once it is generated and published.

See Javadoc.

ServiceCatalogService API for obtaining service providers.

Return a specific service provider

/**
 * Returns a specific service provider.
 *
 * @param service - the service's interface
 * @param serviceProviderId - identifies a service provider
 * @return instance of a service provider for the service
 * @throws FileNotFoundException if the service provider does not exist
 */
<T> T getServiceProvider(Class<T> service, URI serviceProviderId) throws FileNotFoundException;

Return a service provider

/**
 * Returns a service provider.
 *
 * @param service - the service's interface
 * @return instance of a service provider for the service
 * @throws FileNotFoundException if the service does not have a service provider
 */
<T> T getServiceProvider(Class<T> service) throws FileNotFoundException;

Return a service provider for a specific version of the service

/**
 * Returns a service provider for a specific version of the service.
 *
 * @param service - the service's interface
 * @param version - the version of the service
 * @return instance of a service provider for the service
 * @throws IllegalArgumentException if version is invalid
 * @throws FileNotFoundException if the service does not have a service provider
 */
<T> T getServiceProvider(Class<T> service, String version) throws FileNotFoundException;

Return a service provider that satisfies a set of predicates

/**
 * Returns a service provider that satisfies a set of predicates.
 *
 * @param service - the service's interface
 * @param filter - conforms to RFC 1960 grammar
 * @return instance of a service provider for the service
 * @throws FileNotFoundException if the service does not have a service provider
 */
<T> T getServiceProvider(Class<T> service, RFC1960SearchFilter filter)  throws FileNotFoundException;

Returns a service provider that satisfies a simple predicate

/**
 * Return a service provider that satisfies a simple predicate.
 *
 * @param service - the service's interface
 * @param version - the version of the service; can be null
 * @param predicate - in the form key=value
 * @return instance of a service provider for the service
 * @throws IllegalArgumentException if the predicate is invalid
 * @throws FileNotFoundException if the service does not have a service provider
 */
<T> T getServiceProvider(Class<T> service, String version, String predicate) throws FileNotFoundException;

Return a service's RESTful endpoint

/**
 * Returns a service's RESTful endpoint.
 *
 * @param service - the service's interface
 * @param version - the version of the service
 * @return URL
 * @throws IllegalArgumentException if version is invalid
 * @throws FileNotFoundException if the service does not have a service provider
 */
URL getServiceRestfulEndPoint(Class<?> service, String version) throws FileNotFoundException;