Navigation:
Documentation
Archive



Page Tree:

Child pages
  • Person Profile 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} Person Profile

 

 

 

Brief description

Version

This page describes the Person Profile service API, v0.8

To discover the version and other metadata about deployed service code that fulfills this API, please utilize the Service Catalog Service - BDOC.

Overview and Definitions

The Person Profile service manages descriptive information about a Bamboo Person. The descriptive information is largely self-asserted. The entity diagram associated with the Bamboo Person service may be of interest vis-a-vis the information managed by this service; the versioned Bamboo Person schema is authoritative.

A Bamboo Person Profile is sufficiently rich to support search and discovery for users interested in building communities of practice and scholarship. It is not an authoritative, verified, or complete profile of a person. A Bamboo Person Profile may include self-asserted URIs or URLs that identify independently maintained stores of information about the profile's subject (e.g., a VIVO, Zotero, OpenScholar, or Academia.edu profile; or an institutionally-maintained repository of user profile information, such as a web page, an LDAP directory listing, a curriculum vitae (CV), etc.; inclusion of these links permits services that support search and discovery of Bamboo Persons of interest to follow, index, and/or mine the linked data.

For a full description, visit the Person Profile Service Description and Assumptions page of Project Bamboo's development wiki.

Assumptions

  • Group memberships are managed via a Groups service.
  • Contact information is be managed by a Contact Service.

References

Known Issues

Note that the methods are sensitive to the value of the HTTP Accept header. If you receive an error message, please ensure that one of the current valid values is specified in the Accept header when invoking the service:

  • application/xml
  • application/atom+xml
  • text/*
  • application/svg+xml
  • /
  • text/xml
  • application/xhtml+xml

ROA Layer API

RESTful service methods performing Create, Read, Update, Delete, and List functions over a Bamboo Person's Profile keyed on a Bamboo Person identity (BPId). For more on the BPId, see Person Service Contract Description.

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

Person Profile

A Person Profile service is descriptive information about a Bamboo Person.

Create a Person Profile

A client creates a Bamboo Person Profile by supplying a minimum of personal information relating to a specific person as identified by their unique identifier (i.e. BPId).

Preconditions:

  1. Existing Bamboo Person
  2. Existing Bamboo Contact assigned to the Bamboo Person

Calling Method and Arguments

Invoked as an HTTP POST method with a BambooProfile XML document in the body of the HTTP request. Send an HTTP request of the form:

POST /bsp/persons/{BPId}/profile HTTP/1.1

Parameter

Meaning

bpid

The unique identifier for a Bamboo Person

HTTP Body

An instance of a BambooProfile XML document

Example:

POST <url root>/bsp/persons/urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b/profile

Example BambooProfile XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BambooProfile xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://projectbamboo.org/bsp/services/core/person/resources/profile" xmlns:bp="http://projectbamboo.org/bsp/BambooPerson">
    <bp:profileContact>
        <bp:contactId>urn:uuid:ff6acddc-e303-49a7-9c48-7ed79d8483c6</bp:contactId>
    </bp:profileContact>
    <bp:interests>
        <bp:interest>I am interested in Latin editions of the New Testament</bp:interest>
        <bp:visibilityIndicator>false</bp:visibilityIndicator>
        <bp:authorizedPublisher>true</bp:authorizedPublisher>
    </bp:interests>
    <bp:interests>
        <bp:interest>I am interested in Greek editions of the New Testament</bp:interest>
        <bp:visibilityIndicator>false</bp:visibilityIndicator>
    </bp:interests>
    <bp:expertise>
        <bp:expertise>I am an expert in free will</bp:expertise>
        <bp:visibilityIndicator>false</bp:visibilityIndicator>
    </bp:expertise>
    <bp:externalAffiliations>http://somewhere_else.org</bp:externalAffiliations>
    <bp:preferredLanguage>lat</bp:preferredLanguage>
    <bp:languageUsedInScholarships>lat</bp:languageUsedInScholarships>
    <bp:languageUsedInScholarships>grc</bp:languageUsedInScholarships>
    <bp:profileInformation>Test profile</bp:profileInformation>
    <bp:otherProfiles>
        <bp:profileName>Some other profile</bp:profileName>
        <bp:profileUrl>http://some-other-profile.some-site.edu</bp:profileUrl>
        <bp:visibilityIndicator>false</bp:visibilityIndicator>
    </bp:otherProfiles>
    <bp:visibilityIndicator>true</bp:visibilityIndicator>
</BambooProfile>

Response

On success, a response with a "201 Created" HTTP status code will be returned:

Parameter

Meaning

HTTP Header Location

A URL of the form "http://services.projectbamboo.org/bsp/persons/bpid/profile/bppid" where "bpid" is the Bamboo Person identifier  and "bppid" is the Bamboo Profile identifier

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 Post 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

405

Method Not Allowed

The resource already exists

500

Internal Server Error

A service error prevented the resource from being returned

Read a Person Profile

A client requests a Bamboo Person's profile by submitting the person's unique identifier (i.e. BPId) and the profile's unique identifier (BPPId).

Calling Method and Arguments

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

GET /bsp/persons/{BPId}/profile/{BPPId} HTTP/1.1

Parameter

Meaning

BPId

The unique identifier for a Bamboo Person

BPPId

The unique identifier for a Bamboo Profile

Accept Header

application/xml

Example:

GET <url root>/bsp/persons/urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b/profile/urn:uuid:2eaaed0e-31b7-4918-9260-f62bfb95b198

Response

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

Parameter

Meaning

HTTP Body

An instance of a BambooProfile XML document

Example BambooProfile XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BambooProfile 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="http://projectbamboo.org/bsp/services/core/person/resources/profile" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:bp="http://projectbamboo.org/bsp/BambooPerson" xmlns:bsp="http://projectbamboo.org/bsp/resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <bp:bPId>urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b</bp:bPId>
    <bp:profileId>urn:uuid:2eaaed0e-31b7-4918-9260-f62bfb95b198</bp:profileId>
    <bp:profileContact>
        <bp:bPId>urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b</bp:bPId>
        <bp:contactId>urn:uuid:ff6acddc-e303-49a7-9c48-7ed79d8483c6</bp:contactId>
        <bp:name>
            <bp:formattedName>Mr. Desiderius Erasmus</bp:formattedName>
        </bp:name>
        <bp:display>This is the display field</bp:display>
        <bp:contactNote>General address Erasmus University, Rotterdam, Netherlands</bp:contactNote>
        <bp:visibilityIndicator>true</bp:visibilityIndicator>
        <bp:primary>true</bp:primary>
    </bp:profileContact>
    <bp:interests>
        <bp:interest>I am interested in Greek editions of the New Testament</bp:interest>
        <bp:visibilityIndicator>false</bp:visibilityIndicator>
    </bp:interests>
    <bp:interests>
        <bp:interest>I am interested in Latin editions of the New Testament</bp:interest>
        <bp:visibilityIndicator>false</bp:visibilityIndicator>
    </bp:interests>
    <bp:expertise>
        <bp:expertise>I am an expert in free will</bp:expertise>
        <bp:visibilityIndicator>false</bp:visibilityIndicator>
    </bp:expertise>
    <bp:externalAffiliations>http://somewhere_else.org</bp:externalAffiliations>
    <bp:preferredLanguage>lat</bp:preferredLanguage>
    <bp:languageUsedInScholarships>grc</bp:languageUsedInScholarships>
    <bp:languageUsedInScholarships>lat</bp:languageUsedInScholarships>
    <bp:profileInformation>Test profile</bp:profileInformation>
    <bp:otherProfiles>
        <bp:profileName>Some other profile</bp:profileName>
        <bp:profileUrl>http://some-other-profile.some-site.edu</bp:profileUrl>
        <bp:visibilityIndicator>false</bp:visibilityIndicator>
    </bp:otherProfiles>
    <bp:visibilityIndicator>true</bp:visibilityIndicator>
</BambooProfile>

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 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

Update a Person Profile

A client updates a Bamboo Person's profile by submitting the person's unique identifier (i.e. BPId) and an instance of a BambooProfile XML document.

Calling Method and Arguments

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

PUT /bsp/persons/{BPId}/profile HTTP/1.1

Parameter

Meaning

BPId

The unique identifier for a Bamboo Person

Accept Header

application/xml

HTTP Body

An instance of a BambooProfile XML document

See XML sample at Create a Person Profile, above.

Response

On success, a response with a "204 No Content" HTTP status code will be returned.

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 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

Delete a Person Profile

A client deletes a Bamboo Person's profile by submitting the person's unique identifier (i.e. BPId) and the profile's unique identifier (i.e. BPPId).

Calling Method and Arguments

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

DELETE /bsp/persons/{BPId}/profile/{BPPId} HTTP/1.1

Parameter

Meaning

BPId

The unique identifier for a Bamboo Person

BPPId

The unique identifier for a Bamboo Profile

Accept Header

application/xml

Response

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

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 All Profiles for a Bamboo Person

A client requests a list of a Bamboo Person's profiles by submitting the person's unique identifier (i.e. BPId).

Calling Method and Arguments

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

GET /bsp/persons/{BPId}/profile HTTP/1.1

Parameter

Meaning

BPId

The unique identifier for a Bamboo Person

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 profileList XML document

XML Sample

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profileList 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="http://projectbamboo.org/bsp/services/core/person/resources/profile" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:bp="http://projectbamboo.org/bsp/BambooPerson" xmlns:bsp="http://projectbamboo.org/bsp/resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <listHeader>
        <dcterms:created xsi:type="dcterms:W3CDTF">2011-12-20T10:53:21.305-05:00</dcterms:created>
        <dcterms:creator xsi:type="foaf:Agent" rdf:about="Person Service"/>
        <bsp:orderedBy>ascending</bsp:orderedBy>
        <bsp:listLength>1</bsp:listLength>
        <bsp:pageNumber>0</bsp:pageNumber>
        <bsp:pageLength>20</bsp:pageLength>
    </listHeader>
    <profiles>
        <profile rdf:about="http://173.255.250.96:8181/bsp/persons/urn:uuid:ec709dfd-fd7e-49bb-8e60-21f37c36c642/profile/urn:uuid:db94a26c-0173-42e8-8eb7-8bf0b292e28d">
            <name>Mr. Bruce Barton</name>
            <information>I work in the Academic Technology Department at the University of Wisconsin, Madison.</information>
        </profile>
    </profiles>
</profileList>

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

SOA Layer API

Javadoc will be linked once it is generated and published.

See Javadoc.