Person pages: Home | Description | Use Cases | Questions | Models/Adoption/Delegation | Entity Diagrams | Contract
This page is SUPERCEDED by v0.9 documentation in the final documentation set. Cf. Person Service Contract Description v0.9 |
Contract:
{multi-excerpt:name=serviceName}Person{multi-excerpt} |
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 - BDOC. |
The Person Service manages a Project Bamboo Person identifier (bambooPersonId) 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 bambooPersonId– may be associated with one or more SourcedId pairs.
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.
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
|
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>):
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> |
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 |
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 |
A client application which is a member of the Bamboo Trust Federation reads the bambooPersonId 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 <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 |
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 |
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 |
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).
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> |
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 |
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:
|
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 submitting the person's unique identifier (i.e. bambooPersonId) and the Sourced Id's unique identifier (i.e. sourcedIdId).
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 |
On success, a response with a "200 OK" HTTP status code will be returned.
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:
|
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. bambooPersonId) 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 <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> |
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 |
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:
|
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. bambooPersonId)
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 |
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 |
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:
|
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 |
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 <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 |
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> |
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 |
A client requests a list of Bamboo Persons
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 |
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:
TBD |
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 |
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