Navigation:
Documentation
Archive



Page Tree:

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

Brief description

Version

This page describes the Bamboo Person service API, v. 0.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 Service manages a Project Bamboo Person identifier (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.

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 BPId – may be associated with one or more SourcedId pairs.

A Bamboo Contact must be defined in order to create a Bamboo Person Profile, which describes a person in human-accessible terms (such as name, contact information, interests, expertise, and languages used in scholarship). This requirement, combined with the exigencies of development priorities in late 2011, is the reason that the Bamboo Person service currently includes Create and List methods on Bamboo Contact.

The CONTACT related methods will be removed from this service's API on refactoring and instantiation of a standalone CONTACT service.

(This warning block repeated below.)

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

Assumptions

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

References

Known Issues

None.

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 (BPId).

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

Bamboo Person Identifier (BPId)

Create a BPId

A client creates 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>).

Calling Method and Arguments

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

POST /bsp/persons/{IdPId},{NameId} HTTP/1.1

Parameter

Meaning

IdPId

A URL-encoded unique identifier for the Identity Provider

NameId

The identifier assigned to the subject by the Identity Provider

Example:

POST <url root>/bsp/persons/bamboouniversity.edu,desideriuserasmus

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/BPId" where "BPId" 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 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

405

Method Not Allowed

Resource already exists

500

Internal Server Error

A service error prevented the resource from being returned

Read a BPId

A client requests the BPId 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>).

Calling Method and Arguments

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

GET /bsp/persons/sourcedid/{IdPId},{NameId} HTTP/1.1

Parameter

Meaning

IdPId

A URL-encoded unique identifier for the Identity Provider

NameId

The identifier assigned to the subject by the Identity Provider

Example:

GET <url root>/bsp/persons/sourcedid/bamboouniversity.edu,desideriuserasmus

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/BPId" where "BPId" 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 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

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. BPId).

Calling Method and Arguments

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

POST /bsp/persons/{BPId}/sourcedid/{IdPId},{NameId} HTTP/1.1

Parameter

Meaning

BPId

The unique identifier for a Bamboo Person

IdPId

A URL-encoded unique identifier for the Identity Provider

NameId

The identifier assigned to the subject by the Identity Provider

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/BPId" where "BPId" is the 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

400

Bad Request

If either the IdPId or the NameId are missing or zero length

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 supplying an identity provider's unique identifier (i.e. <saml:Issuer>), the identity provider's subject identifier (i.e. <saml:NameID>), and the unique identifier for the Bamboo Person (i.e. BPId).

Calling Method and Arguments

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

DELETE /bsp/persons/{BPId}/sourcedid/{IdPId},{NameId} HTTP/1.1

Parameter

Meaning

BPId

The unique identifier for a Bamboo Person

IdPId

A URL-encoded unique identifier for the Identity Provider

NameId

The identifier assigned to the subject by the Identity Provider

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/person/BPId" where "BPId" is the 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

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. BPId) 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

Calling Method and Arguments

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

PUT /bsp/persons/{BPId}/sourcedid/{BPId}/{IdPId},{NameId} HTTP/1.1

Parameter

Meaning

BPId

The unique identifier for a Bamboo Person. The first occurrence represents the current assignee, the second that to which the sourcedId will now be assigned

IdPId

A URL-encoded unique identifier for the Identity Provider

NameId

The identifier assigned to the subject by the Identity Provider

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/person/BPId" where "BPId" 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

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 BPId

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

  • 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

Calling Method and Arguments

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

GET /bsp/persons/{BPId}/sourcedid/?idpid={IdPId} HTTP/1.1

Parameter

Meaning

BPId

A unique identifier for a Bamboo Person

IdPId

Null for a list of all IDPs | the URL-encoded unique identifier for an Identity Provider for a list containing the SourcedId attributes for a given Identity Provider

Response

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

Parameter

Meaning

HTTP Body

An instance of a SourcedIdList 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

400

Bad Request

The the IdPId is missing or zero length

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 /bsp/persons/{bpid} HTTP/1.1

Parameter

Meaning

bpid

A Bamboo Person Identifier | Null for a list of all Bamboo Persons

Example:

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

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"?>
<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="http://projectbamboo.org/bsp/services/core/person/resources/person" xmlns:bp="http://projectbamboo.org/bsp/BambooPerson" xmlns:bsp="http://projectbamboo.org/bsp/resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <person rdf:about="http://173.255.247.230:8181/bsp/persons/urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b">
        <name>Mr. Desiderius Erasmus</name>
        <email>derasmus@bamboouniversity.edu</email>
    </person>
    <personDetail>
        <contact>
            <bp:display>This is the display field</bp:display>
            <bp:emails>
                <bp:email>derasmus@bamboouniversity.edu</bp:email>
            </bp:emails>
            <bp:telephones>
                <bp:TelephoneType>VOICE</bp:TelephoneType>
                <bp:telephoneNumber>1234-5678</bp:telephoneNumber>
                <bp:locationType>HOME</bp:locationType>
            </bp:telephones>
            <bp:iMs>
                <bp:IMType>SKYPE</bp:IMType>
                <bp:iMAccount>derasmus.bamboouniversity.edu</bp:iMAccount>
            </bp:iMs>
            <bp:contactNote>General address Erasmus University, Rotterdam, Netherlands</bp:contactNote>
            <bp:visibilityIndicator>true</bp:visibilityIndicator>
            <bp:primary>true</bp:primary>
        </contact>
    </personDetail>
</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

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 /bsp/persons/?orderby={orderby} HTTP/1.1

Parameter

Meaning

orderby

sorts the list by: bpid | name | null
If null, the list is sorted by bpid

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"?>
<personList 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="http://projectbamboo.org/bsp/services/core/person/resources/person" xmlns:bp="http://projectbamboo.org/bsp/BambooPerson" xmlns:bsp="http://projectbamboo.org/bsp/resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <listHeader rdf:about="http://173.255.247.230:8181/bsp/persons">
        <dcterms:created xsi:type="dcterms:W3CDTF">2012-07-20T16:27:06.691-04:00</dcterms:created>
        <dcterms:creator xsi:type="foaf:Agent" rdf:about="Person Service"/>
        <bsp:listLength>3</bsp:listLength>
        <bsp:pageNumber>1</bsp:pageNumber>
        <bsp:pageLength>20</bsp:pageLength>
    </listHeader>
    <persons>
        <person rdf:about="http://173.255.247.230:8181/bsp/persons/urn:uuid:813f76f4-bc4b-44d8-ad36-81810f0356d3">
            <name>Mr. Juan Antonio Sanchez y Sanchez jr.</name>
            <email>sanchez99999@yahoo.com</email>
        </person>
        <person rdf:about="http://173.255.247.230:8181/bsp/persons/urn:uuid:813f76f4-bc4b-44d8-ad36-81810f0356d4">
            <name>Mr. Juan Antonio Sanchez y Sanchez jr.</name>
            <email>sanchez99999@yahoo.com</email>
        </person>
        <person rdf:about="http://173.255.247.230:8181/bsp/persons/urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b">
            <name>Mr. Desiderius Erasmus</name>
            <email>derasmus@bamboouniversity.edu</email>
        </person>
    </persons>
</personList>

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

Contact (Bamboo Contact)

A Bamboo Contact must be defined in order to create a Bamboo Person Profile, which describes a person in human-accessible terms (such as name, contact information, interests, expertise, and languages used in scholarship). This requirement, combined with the exigencies of development priorities in late 2011, is the reason that the Bamboo Person service currently includes Create and List methods on Bamboo Contact.

The CONTACT related methods will be removed from this service's API on refactoring and instantiation of a standalone CONTACT service.

(This warning block repeats from above.)

Create a Bamboo Contact

A client creates a Bamboo Contact by supplying both a Bamboo Person Identifier and a valid BambooContactRequest XML document..

Calling Method and Arguments

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

POST /bsp/persons/{bpid}/contact HTTP/1.1

Parameter

Meaning

bpid

A Bamboo Person Identifier

HTTP Body

BambooContactRequest XML document

Example:

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

The BambooContactRequest XML document should be of the form:

<?xml version="1.0" encoding="UTF-8"?>
<BambooContactRequest
xmlns="http://projectbamboo.org/bsp/services/core/person/resources/contact"
xmlns:bp="http://projectbamboo.org/bsp/BambooPerson" >
    <bp:name>
     <formattedName>Desiderius Erasmus</formattedName>
      <bp:partNames>
        <bp:partNameContent>Mr.</bp:partNameContent>
        <bp:NamePartType>HONORIFIC_PREFIX</bp:NamePartType>
        <bp:NamePartLang>nl</bp:NamePartLang>
      </bp:partNames>
      <bp:partNames>
        <bp:partNameContent>Desiderius</bp:partNameContent>
        <bp:NamePartType>NAME_GIVEN</bp:NamePartType>
        <bp:NamePartLang>nld</bp:NamePartLang>
      </bp:partNames>
      <bp:partNames>
        <bp:partNameContent>Erasmus</bp:partNameContent>
        <bp:NamePartType>NAME_FAMILY_PATERNAL</bp:NamePartType>
        <bp:NamePartLang>nld</bp:NamePartLang>
      </bp:partNames>
    </bp:name>
    <bp:display>This is the display field</bp:display>
    <bp:emails>
      <bp:email>derasmus@bamboouniversity.edu</bp:email>
    </bp:emails>
    <bp:telephones>
      <bp:TelephoneType>VOICE</bp:TelephoneType>
      <bp:telephoneNumber>1234-5678</bp:telephoneNumber>
      <bp:locationType>HOME</bp:locationType>
    </bp:telephones>
    <bp:iMs>
      <bp:IMType>SKYPE</bp:IMType>
      <bp:iMAccount>derasmus.bamboouniversity.edu</bp:iMAccount>
      <bp:locationType>WORK</bp:locationType>
    </bp:iMs>
    <bp:addresses>
      <bp:streetAddresses>Burgemeester Oudlaan 50</bp:streetAddresses>
      <bp:streetAddresses>3062 PA</bp:streetAddresses>
      <bp:locality>Rotterdam</bp:locality>
      <bp:region>NL-RR</bp:region>
      <bp:postalCode>3062 PA</bp:postalCode>
      <bp:country>NL</bp:country>
      <bp:locationType>WORK</bp:locationType>
    </bp:addresses>
    <bp:contactNote>General address Erasmus University, Rotterdam, Netherlands</bp:contactNote>
    <bp:visibilityIndicator>true</bp:visibilityIndicator>
    <bp:primary>true</bp:primary>
</BambooContactRequest>

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/{bpid}/contact/{bcid}"

where "bcid" is the Bamboo Contact identifier

Example:

201 Created <url root>/bsp/persons/urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b/contact/urn:uuid:ff6acddc-e303-49a7-9c48-7ed79d8483c6

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

405

Method Not Allowed

Resource already exists

500

Internal Server Error

A service error prevented the resource from being returned

List all Bamboo Contacts for a Person

A client requests a list of all Bamboo Contacts for a Bamboo Person

Calling Method and Arguments

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

GET /bsp/persons/{bpid}/contact HTTP/1.1

Parameter

Meaning

bpid

A Bamboo Person Identifier

Example:

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

Response

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

Parameter

Meaning

HTTP Body

An instance of a contactList XML document

Example contactList XML document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<contactList 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:bp="http://projectbamboo.org/bsp/BambooPerson" xmlns:bsp="http://projectbamboo.org/bsp/resource" xmlns="http://projectbamboo.org/bsp/services/core/person/resources/contact" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <listHeader rdf:about="http://173.255.247.230:8181/bsp/persons/urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b/contact/">
        <dcterms:created xsi:type="dcterms:W3CDTF">2012-07-18T19:46:05.601-04:00</dcterms:created>
        <dcterms:creator xsi:type="foaf:Agent" rdf:about="Person Service"/>
        <bsp:listLength>1</bsp:listLength>
        <bsp:pageNumber>1</bsp:pageNumber>
        <bsp:pageLength>20</bsp:pageLength>
    </listHeader>
    <contacts>
        <contact rdf:about="http://173.255.247.230:8181/bsp/persons/urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b/contact/urn:uuid:ff6acddc-e303-49a7-9c48-7ed79d8483c6">
            <name>Mr. Desiderius Erasmus</name>
            <emails>
                <bp:email>derasmus@bamboouniversity.edu</bp:email>
            </emails>
        </contact>
    </contacts>
</contactList>

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

404

Not Found

 

The Bamboo Person requested does not exist

 

SOA Layer API

Javadoc will be linked once it is generated and published.

See Javadoc.