Brief description

Version

This page describes the Bamboo Person service API, v. 0.9.

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

Overview and Definitions

The Person Service manages a Project Bamboo Person identifier (bambooPersonId or BPId) that is unique across the Project Bamboo namespace, and associates it to user identifiers belonging to a Project Bamboo Person, as the identifiers are presented by any number of identity providers. The purpose of a Bamboo Person identifier is to uniquely identify a person who utilizes Bamboo technology independent of the one or more methods s/he uses to log in (assert identity).

User identifiers take the form of an identifier for an Identity Provider (IdP), and a identifier for a User unique in the IdP's namespace. The term "SourcedId" is used to name this combination of identifiers: User Identifier + IdP Identifier.

A single Bamboo Person – keyed on bambooPersonId (BPId) – may be associated with one or more SourcedId pairs.

The following required conventions are to be observed by clients in constructing a SourcedId:

The identity provider is to be represented as described in Conventions for representing Identity Providers in the Bamboo Trust Federation. Examples: http://berkeley.edu,http://google.com.
The user identifer, unique in the IdP's name space, is to be one-way converted to a SHA-256 hash prior to inclusion in the SourcedId (i.e., the actual user identifier supplied by the IdP is not passed to the Person service, only an SHA-256 hash of that value is passed)

The significance of these conventions are described in the Bamboo IAM from a client application's perspective section of the page Identity and Access Management - Authentication and Authorization.

Assumptions

See warning box re: required conventions to do with SourcedId, in Overview and Definitions, above.

References

${REPOSITORY_ROOT} is http://svn.code.sf.net/p/projectbamboo/code/

Codebase: ${REPOSITORY_ROOT}/platform-services/bsp/trunk/bsp/core-services/person-service/

Known Issues

n/a

ROA Layer API

RESTful service methods performing Create, Read, Update, Delete, and List functions over a Bamboo Person's Sourced Identity(s) based on their Bamboo Person identity (bambooPersonId).

Base URLs

It is assumed in this documentation that no centrally-run instances of the Bamboo Services Platform will be running after the project ends on 31 March 2013. Therefore, base URLs are assumed to be on a developer's machine, localhost. The base URL with a port number assumes that the BSP is running unsecured; the URL without a port number assumes that security is enforced and Apache Web Server is intercepting and redirecting service calls. Please see the page Identity and Access Management - Authentication and Authorization for context, as well as links to installation and configuration instructions for secured instances of BSP.

Note that ONLY services at v0.9 or greater will run properly in a secured instance of the BSP.

Currently available base URLs:

Client Responsibilities in Requests to Secured BSP Web Services

This section of the Service API documentation describes a client application's responsibilities when making requests to secured Web Services hosted on the Bamboo Services Platform (including this service).

A secured instance of the Bamboo Services Platform (BSP) implies a significant set of installation and configuration tasks for which the operator of the BSP is responsible. These are described in overview on the wiki page Identity and Access Management - Authentication and Authorization, and in detail on pages linked from that one.

(1) A client must be configured as a Trusted Application if requests are to be treated other than as Anonymous

A client application – whether a web app or a simple testing client such as Firefox Poster or curl – may make requests anonymously or as a "Trusted Application." Only a Trusted Application may assert the identity of a user on behalf of whom the request is made, and scoped roles to be assigned to that user; Bamboo Services trust such clients to assert the identity and assigned-roles only of users who have authenticated in the current session of application activity. (A special-case type of client application, termed Innovation Licensed applications, are trusted to assert the identity of and roles assigned to a fixed set of special-case users without those users having to authenticate in the current session.)

Configuration of client applications are described in detail in this wiki page: Configure Apache Web Server for Client Auth. It is assumed in #2, below, that this configuration has been performed.

(2) A Trusted client is expected to pass HTTP Request Headers to identify itself and an authenticated user

A client application that is Trusted in the security context of the Bamboo Trust Federation (cf. Identity and Access Management - Authentication and Authorization) must augment each request to a service hosted by a secured instance of the Bamboo Services Platform (BSP) with a set of HTTP headers, as follows:

X-Bamboo-AppID: A UUID that identifies the client research environment, application, tool, or service; this UUID is issued as part of the process of registering a trusted client in the Bamboo Trust Federation as described in overview on the page Identity and Access Management - Authentication and Authorization; and in detail with respect to physical establishment of trust on the page Configure Apache Web Server for Client Auth. The value of this header is linked to the X.509 certificate by which the application establishes an SSL connection to the BSP host in the registration process, and a match between this Application ID and the linked X.509 certificate is checked by the BSP on receipt of every request.
X-Bamboo-BPID: A UUID that identifies the logged-in user on whose behalf the request is being sent; this value, a Bamboo Person Identifier, or BPId, is obtained via a call to the Person Service that occurs in time between user login and any other service request. See the Read a BambooPersonId method of the Person Service API for details. [^†]
X-Bamboo-Roles: A pipe-delimited (|) set of scoped roles asserted by the trusted client to belong to the logged-in user, of the form role@domain, which are to be evaluated as factors in the determination of whether the request satisfies policies (access restrictions) that apply to the requested resource. If a user is authenticated, the client is expected to include the role undefined@domain where domain identifies the organization that authenticated the user (example: undefined@google.com is a client app's assertion that the user authenticated to Google). This header is otherwise optional (depending on policies governing the requested resource that may require one or more scoped roles for access to be permitted). Example of multiple roles asserted in this header: roleA@domainOne.xxx|roleB@domainTwo [^‡]

[^†] The value of X-Bamboo-BPID is set to the identifier for the application itself (X-Bamboo-AppID) when a client application calls the Person Service to create a new Bamboo Person Identifier; or to retrieve the BPId for a user based on the identifier of the IdP with which she has logged in and an SHA-256 hash of that IdP's user identifier for the logged-in person.

[^‡] Policies and policy evaluation are described on the page Authorization and Policy. Also see Conventions for representing Identity Providers in the Bamboo Trust Federation.

Schema

${REPOSITORY_ROOT} is http://svn.code.sf.net/p/projectbamboo/code/

${REPOSITORY_ROOT}/platform-services/bsp/trunk/bsp/core-services/person-service/person-service-domain/src/main/resources/BambooPerson.xsd

Bamboo Person Identifier (bambooPersonId)

Create a bambooPersonId

A client application which is a member of the Bamboo Trust Federation creates a Bamboo Person by supplying a SourcedId, a combination of an identity provider's unique identifier (i.e. <saml:Issuer>) and the identity provider's subject identifier (i.e. <saml:NameID>):

A minimum of one SourcedId is required to create a bambooPersonId
Multiple SourcedIds can be provided if the bamboo person is to be associated with multiple identity providers
Additional SourcedIds can be added later

See Overview and Definitions, above, for requirements in the construction of a SourcedId.

Calling Method and Arguments

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

POST <url root>/bsp/persons HTTP/1.1

Parameter	Meaning
HTTP Body	An instance of a bambooPerson XML document containing valid SourcedId data

Example:

POST <url root>/bsp/persons

Example XML document:

<?xml version="1.0" encoding="UTF-8"?>
<person:bambooPerson xmlns:person="http://projectbamboo.org/bsp/BambooPerson" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <person:sourcedId>
    <person:sourcedIdName>One SourcedId</person:sourcedIdName>
    <person:sourcedIdKey>
      <person:idPId>http://someidp.org</person:idPId>
      <person:userId>7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd100126d9069</person:userId>
    </person:sourcedIdKey>
  </person:sourcedId>
<person:sourcedId>
    <person:sourcedIdName>Two SourcedId</person:sourcedIdName>
    <person:sourcedIdKey>
      <person:idPId>http://someidp.org</person:idPId>
      <person:userId>7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677264addd100126d9069</person:userId>
    </person:sourcedIdKey>
  </person:sourcedId>
</person:bambooPerson>

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 "/bsp/persons/bambooPersonId" where "bambooPersonId" is the Bamboo Person identifier

Example Location Header:

<url root>/bsp/persons/urn:uuid:0293af26-9502-44e5-8e22-bdc1bf5eafa4

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
400	Bad Request	If either the IdPId or the NameId are missing or zero length
401	Unauthorized	The client submitting the request is not a member of the Bamboo Trust Federation group
500	Internal Server Error	A service error prevented the resource from being returned

Read a BambooPersonId

A client application which is a member of the Bamboo Trust Federation reads the bambooPersonId for a Bamboo Person by supplying elements of a SourcedId: an identity provider's unique identifier (i.e. <saml:Issuer>) and the identity provider's subject identifier (i.e. <saml:NameID>).

See Overview and Definitions, above, for requirements in the construction of a SourcedId (and its elements)

Calling Method and Arguments

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

GET <url root>/bsp/persons/sourcedid/?idpid={idpid}&userid={userid} HTTP/1.1

Parameter	Meaning
idpid	Identity provider's unique identifier
userid	Identity provider's subject identifier

Example:

GET <url root>/bsp/persons/sourcedid/?idpid=http://someidp.org&userid=7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd100126d9068

Response

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

Parameter	Meaning
HTTP Header Location	A URL of the form "/bsp/persons/bambooPersonId" where "bambooPersonId" is the Bamboo Person identifier

Example Location Header:

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

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
400	Bad Request	If either the IdPId or the NameId are missing or zero length
401	Unauthorized	The client submitting the request is not a member of the Bamboo Trust Federation group
404	Not Found	The resource requested for reading does not exist
500	Internal Server Error	A service error prevented the resource from being returned

SourcedId (User Identifier + Identity Provider Identifier)

Create a SourcedId

A client creates a SourcedId for a Bamboo Person by supplying an identity provider's unique identifier (i.e. <saml:Issuer>) and the identity provider's subject identifier (i.e. <saml:NameID>), and the unique identifier for the Bamboo Person (i.e. bambooPersonId).

See Overview and Definitions, above, for requirements in the construction of a SourcedId.

Calling Method and Arguments

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

POST <url root>/bsp/persons/{bambooPersonId}/sourcedids HTTP/1.1

Parameter	Meaning
bambooPersonId	The unique identifier for a Bamboo Person
HTTP Body	An instance of a bambooPerson XML document containing valid SourcedId data

Example XML document:

<?xml version="1.0" encoding="UTF-8"?>
<person:bambooPerson xmlns:person="http://projectbamboo.org/bsp/BambooPerson" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <person:sourcedId>
    <person:sourcedIdName>One SourcedId</person:sourcedIdName>
    <person:sourcedIdKey>
      <person:idPId>http://someidp.org</person:idPId>
      <person:userId>7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd100126d9069</person:userId>
    </person:sourcedIdKey>
  </person:sourcedId>
</person:bambooPerson>

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 "<url root>/bsp/persons/bambooPersonId/sourcedids/sourcedidid" where "bambooPersonId" is the Bamboo Person identifier and "sourcedidid" is the Sourced Id 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 Get request:

Error (Status Code)	Meaning	Returned When
401	Unauthorized	One of: The client submitting the request is not a member of the Bamboo Trust Federation group The bambooPersonId of the user making the request is not the same as the bambooPersonId provided in the URL
404	Not Found	The Bamboo Person requested for does not exist
405	Method Not Allowed	The SourcedId already exists
500	Internal Server Error	A service error prevented the resource from being returned

Delete a SourcedId

A client deletes a SourcedId for a Bamboo Person by submitting the person's unique identifier (i.e. bambooPersonId) and the Sourced Id's unique identifier (i.e. sourcedIdId).

See Overview and Definitions, above, for requirements in the construction of a SourcedId.

Calling Method and Arguments

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

DELETE <url root>/bsp/persons/{bambooPersonId}/sourcedids/{sourcedIdId} HTTP/1.1

Parameter	Meaning
bambooPersonId	The unique identifier for a Bamboo Person
sourcedIdId	The unique identifier for a Sourced Id

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	One of: The client submitting the request is not a member of the Bamboo Trust Federation group The bambooPersonId of the user making the request is not the same as the bambooPersonId assigned to the SourcedId
404	Bad Request	If either the IdPId or the NameId are missing or zero length
404	Not Found	The Bamboo Person or SourcedId requested for reading does not exist
500	Internal Server Error	A service error prevented the resource from being returned

Update a SourcedId

A client reassigns a SourcedId from one Bamboo Person to another Bamboo Person by supplying an identity provider's unique identifier (i.e. <saml:Issuer>), the identity provider's subject identifier (i.e. <saml:NameID>), the unique identifier for the Bamboo Person (i.e. bambooPersonId) currently assigned the sourcedId, and the unique identifier for the Bamboo Person to which the sourcedId will be assigned.

If the Identity Provider's unique identifier is invalid the service will return an "Unauthorized" response
If both the Bamboo Person identifiers are known to the service, the new BPId associated with the sourcedId is returned otherwise the service returns a 'Not Found' message

See Overview and Definitions, above, for requirements in the construction of a SourcedId.

Calling Method and Arguments

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

PUT <url root>/bsp/persons/{bambooPersonId}/sourcedids HTTP/1.1

Parameter	Meaning
bambooPersonId	The unique identifier for a Bamboo Person, representing the person to which the sourcedId will now be assigned
HTTP Body	An instance of a bambooPerson XML document containing valid SourcedId data

Example XML document:

<?xml version="1.0" encoding="UTF-8"?>
<person:bambooPerson xmlns:person="http://projectbamboo.org/bsp/BambooPerson" xmlns:xs="http://www.w3.org/2001/XMLSchema">
 <person:bambooPersonId>urn:uuid:5c6c0333-5ad6-4e97-b8c2-d7f18624b9a7</person:bambooPersonId>
 <person:sourcedId>
    <person:sourcedIdName>One SourcedId</person:sourcedIdName>
    <person:sourcedIdKey>
      <person:idPId>http://someidp.org</person:idPId>
      <person:userId>7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd100126d9069</person:userId>
    </person:sourcedIdKey>
  </person:sourcedId>
</person:bambooPerson>

Response

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

Parameter	Meaning
HTTP Header Location	A URL of the form "<url root>/bsp/person/bambooPersonId" where "bambooPersonId" is the target Bamboo Person 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 Get request:

Error (Status Code)	Meaning	Returned When
401	Unauthorized	One of: The client submitting the request is not a member of the Bamboo Trust Federation group The bambooPersonId of the user making the request is not the same as e bambooPersonId assigned to the SourcedId
400	Bad Request	If either the IdPId or the NameId are missing or zero length
404	Not Found	The Bamboo Person or SourcedId requested for reading does not exist
500	Internal Server Error	A service error prevented the resource from being returned

List all SourcedIds for a bambooPersonId

A client requests a list of SourcedIds for a Bamboo Person by supplying the Bamboo Person's unique identifier (i.e. bambooPersonId)

If the Bamboo Person's identifier is known to the service, a list of all SourcedIds associated with that person will be returned otherwise the service returns a 'Not Found' message
To obtain a list filtered by a specific idPId, specify the idPId in the value argument of the query string. If no query string is provided, the list will contain all SourcedIds for the Bamboo Person

See Overview and Definitions, above, for requirements in the construction of a SourcedId (and its elements).

Calling Method and Arguments

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

GET <url root>/bsp/persons/{bambooPersonId}/sourcedids/?filter=idpid&value={idPId} HTTP/1.1

Parameter	Meaning
bambooPersonId	A unique identifier for a Bamboo Person
idPId	The unique identifier for an Identity Provider

Example:

GET <url root>/bsp/persons/urn:uuid:5c6c0333-5ad6-4e97-b8c2-d7f18624b9a7/sourcedids/?filter=idpid&value=http://someidp.org

Response

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

Parameter	Meaning
HTTP Body	An instance of a BambooPerson XML document

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	One of: The client submitting the request is not a member of the Bamboo Trust Federation group The bambooPersonId of the user making the request is not the same as the bambooPersonId provided in the URL
400	Bad Request	The the idPId, if provided, is invalid
404	Not Found	The Bamboo Person requested does not exist
500	Internal Server Error	A service error prevented the resource from being returned

Person (BambooPerson)

Read a Bamboo Person

A client requests a Bamboo Person by supplying the Bamboo Person's unique identifier

Calling Method and Arguments

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

GET <url root>/bsp/persons/{bambooPersonId} HTTP/1.1

Parameter	Meaning
bambooPersonId	A Bamboo Person Identifier \| Null for a list of all Bamboo Persons

Example:

GET <url root>/bsp/persons/urn:uuid:570a60f3-1ac7-48c3-8984-0d48bdb38923

Response

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

Parameter	Meaning
HTTP Body	An instance of a BambooPerson XML document

Example BambooPerson XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<person:bambooPerson 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:contacts="http://projectbamboo.org/bsp/services/core/contact" xmlns:person="http://projectbamboo.org/bsp/BambooPerson" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <dcterms:subject/>
    <dcterms:creator xsi:type="dcterms:URI">urn:uuid:99999999-9999-9999-9999-999999999999</dcterms:creator>
    <dcterms:created xsi:type="dcterms:W3CDTF">2012-09-21T09:41:44.651-07:00</dcterms:created>
    <bsp:modifier>urn:uuid:99999999-9999-9999-9999-999999999999</bsp:modifier>
    <dcterms:modified xsi:type="dcterms:W3CDTF">2012-09-21T09:41:44.713-07:00</dcterms:modified>
    <person:bambooPersonId>urn:uuid:570a60f3-1ac7-48c3-8984-0d48bdb38923</person:bambooPersonId>
    <person:sourcedId>
        <dcterms:subject/>
        <dcterms:creator xsi:type="dcterms:URI">urn:uuid:570a60f3-1ac7-48c3-8984-0d48bdb38923</dcterms:creator>
        <bsp:modifier>urn:uuid:99999999-9999-9999-9999-999999999999</bsp:modifier>
        <person:sourcedIdId>urn:uuid:c08e74ca-8341-4a76-a591-bf0d38de5534</person:sourcedIdId>
        <person:sourcedIdName>One SourcedId</person:sourcedIdName>
        <person:bambooPersonId>urn:uuid:570a60f3-1ac7-48c3-8984-0d48bdb38923</person:bambooPersonId>
        <person:sourcedIdKey>
            <idPId>http://someidp.org</idPId>
            <userId>7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd100126d9069</userId>
            <person:idPId>http://someidp.org</person:idPId>
            <person:userId>7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd100126d9069</person:userId>
        </person:sourcedIdKey>
        <person:accountNonExpired>true</person:accountNonExpired>
        <person:accountNonLocked>true</person:accountNonLocked>
        <person:credentialsNonExpired>true</person:credentialsNonExpired>
        <person:enabled>true</person:enabled>
    </person:sourcedId>
    <person:sourcedId>
        <dcterms:subject/>
        <dcterms:creator xsi:type="dcterms:URI">urn:uuid:570a60f3-1ac7-48c3-8984-0d48bdb38923</dcterms:creator>
        <bsp:modifier>urn:uuid:99999999-9999-9999-9999-999999999999</bsp:modifier>
        <person:sourcedIdId>urn:uuid:f7a3ecee-6e25-477c-9b18-52f72c9e0333</person:sourcedIdId>
        <person:sourcedIdName>Two SourcedId</person:sourcedIdName>
        <person:bambooPersonId>urn:uuid:570a60f3-1ac7-48c3-8984-0d48bdb38923</person:bambooPersonId>
        <person:sourcedIdKey>
            <idPId>http://someidp.org</idPId>
            <userId>7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677264addd100126d9069</userId>
            <person:idPId>http://someidp.org</person:idPId>
            <person:userId>7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677264addd100126d9069</person:userId>
        </person:sourcedIdKey>
        <person:accountNonExpired>true</person:accountNonExpired>
        <person:accountNonLocked>true</person:accountNonLocked>
        <person:credentialsNonExpired>true</person:credentialsNonExpired>
        <person:enabled>true</person:enabled>
    </person:sourcedId>
    <person:bambooProfile person:confidential="false" person:primary="false">
        <dcterms:subject/>
        <dcterms:creator xsi:type="dcterms:URI">urn:uuid:570a60f3-1ac7-48c3-8984-0d48bdb38923</dcterms:creator>
        <dcterms:created xsi:type="dcterms:W3CDTF">2012-09-21T09:41:44.713-07:00</dcterms:created>
        <bsp:modifier>urn:uuid:99999999-9999-9999-9999-999999999999</bsp:modifier>
        <dcterms:modified xsi:type="dcterms:W3CDTF">2012-09-21T09:41:44.713-07:00</dcterms:modified>
        <person:profileId>urn:uuid:5f9a46ed-4840-46be-8ddf-4105da194ff4</person:profileId>
        <person:profileInformation>A new profile</person:profileInformation>
        <person:bambooPersonId>urn:uuid:570a60f3-1ac7-48c3-8984-0d48bdb38923</person:bambooPersonId>
        <contacts:bambooContact>
            <dcterms:subject/>
            <dcterms:creator xsi:type="dcterms:URI">urn:uuid:99999999-9999-9999-9999-999999999999</dcterms:creator>
            <dcterms:created xsi:type="dcterms:W3CDTF">2012-09-21T09:42:49.252-07:00</dcterms:created>
            <bsp:modifier>urn:uuid:99999999-9999-9999-9999-999999999999</bsp:modifier>
            <dcterms:modified xsi:type="dcterms:W3CDTF">2012-09-21T09:42:49.252-07:00</dcterms:modified>
            <contacts:contactId>urn:uuid:412ce852-ed1e-4343-8cab-dd5fd64e8ba3</contacts:contactId>
            <contacts:contactNote>A new Poster tested contact</contacts:contactNote>
            <contacts:emails>
                <email>falvarez@berkeley.edu</email>
                <contacts:email>falvarez@berkeley.edu</contacts:email>
            </contacts:emails>
            <contacts:emails>
                <email>falvarez@berkeley.edu</email>
                <contacts:email>falvarez@berkeley.edu</contacts:email>
            </contacts:emails>
            <contacts:displayName></contacts:displayName>
            <contacts:partNames>
                <contacts:partNameType>HONORIFIC_PREFIX</contacts:partNameType>
                <contacts:partNameContent>Mr.</contacts:partNameContent>
                <contacts:partNameLang>eng</contacts:partNameLang>
            </contacts:partNames>
            <contacts:partNames>
                <contacts:partNameType>NAME_GIVEN</contacts:partNameType>
                <contacts:partNameContent>Fernando</contacts:partNameContent>
                <contacts:partNameLang>spa</contacts:partNameLang>
            </contacts:partNames>
            <contacts:partNames>
                <contacts:partNameType>NAME_FAMILY_PATERNAL</contacts:partNameType>
                <contacts:partNameContent>Alvarez</contacts:partNameContent>
                <contacts:partNameLang>spa</contacts:partNameLang>
            </contacts:partNames>
            <contacts:partNames>
                <contacts:partNameType>NAME_FAMILY_MATERNAL</contacts:partNameType>
                <contacts:partNameContent>Cadena</contacts:partNameContent>
                <contacts:partNameLang>spa</contacts:partNameLang>
            </contacts:partNames>
            <contacts:partNames>
                <contacts:partNameType>HONORIFIC_SUFFIX</contacts:partNameType>
                <contacts:partNameContent>PMP</contacts:partNameContent>
                <contacts:partNameLang>eng</contacts:partNameLang>
            </contacts:partNames>
            <contacts:telephones>
                <contacts:telephoneType>VOICE</contacts:telephoneType>
                <contacts:telephoneNumber>415-555-1212</contacts:telephoneNumber>
                <contacts:locationType>HOME</contacts:locationType>
            </contacts:telephones>
            <contacts:telephones>
                <contacts:telephoneType>SMS</contacts:telephoneType>
                <contacts:telephoneNumber>650-555-1212</contacts:telephoneNumber>
                <contacts:locationType>SABBATICAL</contacts:locationType>
            </contacts:telephones>
            <contacts:iMs>
                <contacts:instantMessagingType>SKYPE</contacts:instantMessagingType>
                <contacts:account>falvarez@berkeley.edu</contacts:account>
                <contacts:locationType>WORK</contacts:locationType>
            </contacts:iMs>
            <contacts:addresses>
                <contacts:streetAddress1>123 Main St.</contacts:streetAddress1>
                <contacts:streetAddress2>2nd fl</contacts:streetAddress2>
                <contacts:streetAddress3>By the south window</contacts:streetAddress3>
                <contacts:locality>Berkeley</contacts:locality>
                <contacts:region>CA</contacts:region>
                <contacts:postalCode>94105</contacts:postalCode>
                <contacts:country>USA</contacts:country>
                <contacts:locationType>WORK</contacts:locationType>
            </contacts:addresses>
        </contacts:bambooContact>
        <person:interests person:confidential="false">
            <person:interest>An interest</person:interest>
        </person:interests>
        <person:expertises person:confidential="false">
            <person:expertise>An expertise</person:expertise>
        </person:expertises>
        <person:externalAffiliations>http://berkeley.org</person:externalAffiliations>
        <person:preferredLanguage>spa</person:preferredLanguage>
        <person:languageUsedInScholarships>eng</person:languageUsedInScholarships>
        <person:otherProfiles person:confidential="false">
            <person:profileName>Some other profile</person:profileName>
            <person:profileUrl>http://tempuri.org</person:profileUrl>
        </person:otherProfiles>
        <person:authorizedPublisher>true</person:authorizedPublisher>
    </person:bambooProfile>
</person:bambooPerson>

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 user making the request is anonymous
400	Bad Request	The Bamboo Person Identifier is not a URN
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 Bamboo Persons

A client requests a list of Bamboo Persons

Calling Method and Arguments

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

GET <url root>/bsp/persons HTTP/1.1

Parameter	Meaning
TBD

Example:

GET <url root>/bsp/persons

Response

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

Parameter	Meaning
HTTP Body	An instance of a BambooPersonList XML document

Example BambooPersonList XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<person: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:dcterms="http://purl.org/dc/terms/" xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:bsp="http://projectbamboo.org/bsp/resource" xmlns:contacts="http://projectbamboo.org/bsp/services/core/contact" xmlns:person="http://projectbamboo.org/bsp/BambooPerson" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <bsp:listMetadata>
        <dcterms:creator xsi:type="foaf:Agent" rdf:about="persons"/>
        <dcterms:created xsi:type="dcterms:W3CDTF">2013-04-11T15:32:51.906-07:00</dcterms:created>
        <bsp:orderedBy>ascending</bsp:orderedBy>
        <bsp:listLength>1</bsp:listLength>
        <bsp:pageNumber>1</bsp:pageNumber>
        <bsp:pageLength>20</bsp:pageLength>
    </bsp:listMetadata>
    <bsp:resource xsi:type="person:BambooPersonSummaryType" rdf:about="http://localhost:8181/bsp/persons/urn:uuid:0da3ac2c-e4ab-4849-956d-b50079ef9de2">
        <dcterms:subject>Mr. Desiderius Erasmus</dcterms:subject>
        <person:name>Mr. Desiderius Erasmus</person:name>
        <person:emails>
            <email>derasmus@bamboouniversity.edu</email>
            <contacts:email>derasmus@bamboouniversity.edu</contacts:email>
        </person:emails>
        <person:emails>
            <email>derasmus@google.com</email>
            <contacts:email>derasmus@google.com</contacts:email>
        </person:emails>
    </bsp:resource>
</person: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
400	Bad Request	orderby is invalid
500	Internal Server Error	A service error prevented the resource from being returned

SOA Layer API

See generated Javadoc for this service. Packages are org.projectbamboo.bsp.services.core.person.*.

Child pages

Person Service Contract Description v0.9-alpha

Brief description

Version

Overview and Definitions

Assumptions

References

Known Issues

ROA Layer API

Base URLs

Client Responsibilities in Requests to Secured BSP Web Services

(1) A client must be configured as a Trusted Application if requests are to be treated other than as Anonymous

(2) A Trusted client is expected to pass HTTP Request Headers to identify itself and an authenticated user

Schema

Bamboo Person Identifier (bambooPersonId)

Create a bambooPersonId

Calling Method and Arguments

Response

Exceptions

Read a BambooPersonId

Calling Method and Arguments

Response

Exceptions

SourcedId (User Identifier + Identity Provider Identifier)

Create a SourcedId

Calling Method and Arguments

Response

Exceptions

Delete a SourcedId

Calling Method and Arguments

Response

Exceptions

Update a SourcedId

Calling Method and Arguments

Response

Exceptions

List all SourcedIds for a bambooPersonId

Calling Method and Arguments

Response

Exceptions

Person (BambooPerson)

Read a Bamboo Person

Calling Method and Arguments

Response

Exceptions

List all Bamboo Persons

Calling Method and Arguments

Response

Exceptions

SOA Layer API