Navigation:
Documentation
Archive



Page Tree:

Child pages
  • Person Profile Service Contract Description v0.8 - BDOC

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

Contract:

 

 

Wiki Markup
{multi-excerpt:name=serviceName}Person Profile{multi-excerpt}

 

 

 

Table of Contents
maxLevel3
minLevel1

Brief description

Version

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

Note

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

Excerpt Include
Web Service API Base URLs - CURRENT - BDOC
Web Service API Base URLs - CURRENT - BDOC
nopaneltrue

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:

Code Block
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:

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

Example BambooProfile XML document:

Code Block
<?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:

Code Block
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:

Code Block
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:

Code Block
<?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:

Code Block
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:

Code Block
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:

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

Code Block
<?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

Note

Javadoc will be linked once it is generated and published.

See Javadoc.