Navigation:
Documentation
Archive
Page Tree:
This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.
Person pages: Home | Description | Use Cases | Questions | Models/Adoption/Delegation | Entity Diagrams | Contract
Contract:
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.
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.
For assumptions implicit in this service's functionality, visit the Person Service Description and Assumptions page of Project Bamboo's development wiki.
None.
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).
Sample on this page is hard-coded text; actual pages will generally include URLs from a master page describing Prod and QA URLs, and perhaps others as the project wishes to make (for example) the Continuous Integration instance visible.
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>).
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
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
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 |
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>).
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
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
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 |
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).
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 |
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 |
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 |
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).
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 |
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 |
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 |
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.
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 |
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 |
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 |
A client requests a list of SourcedIds for a Bamboo Person by supplying the Bamboo Person's unique identifier (i.e. BPId)
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 |
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 |
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 |
A client requests a Bamboo Person by supplying the Bamboo Person's unique identifier
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
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>
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 |
A client requests a list of Bamboo Persons
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 |
Example:
GET <url root>/bsp/persons
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>
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 |
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.)
A client creates a Bamboo Contact by supplying both a Bamboo Person Identifier and a valid BambooContactRequest XML document..
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>
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
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 |
A client requests a list of all Bamboo Contacts for a Bamboo Person
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
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>
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 |
|
Javadoc will be linked once it is generated and published.
See Javadoc.
Person pages: Home | Description | Use Cases | Questions | Models/Adoption/Delegation | Entity Diagrams | Contract