Navigation:
Documentation
Archive
Page Tree:
This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.
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 page describes the Contact service API, version 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 Contact Service provides a RESTful API for creating, reading, updating, deleting, and listing Bamboo Contact information within BSP. Contact information is associated with Bamboo Person Profiles, and may be associated with other entities.
n/a
None
RESTful service methods performing Create, Read, Update, Delete, and List functions over Bamboo Contacts.
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:
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. 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. 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. [†] 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.(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
${REPOSITORY_ROOT} is http://svn.code.sf.net/p/projectbamboo/code/
A Bamboo Contact contains the following information about an entity (e.g. a person) :
A client creates a Bamboo Contact by supplying a valid BambooContact XML document. A minimum of one email account for the entity is required.
Invoked as an HTTP POST method. Send an HTTP request of the form:
POST <url root>/bsp/contacts HTTP/1.1
Parameter | Meaning |
---|---|
HTTP Body | An instance of a bambooContact XML document |
Example:
POST <url root>/bsp/contacts
Example bambooContact XML document:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <contacts:bambooContact xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:contacts="http://projectbamboo.org/bsp/services/core/contact" > <contacts:contactNote>A new Poster tested contact</contacts:contactNote> <contacts:emails> <contacts:email>falvarez@berkeley.edu</contacts:email> </contacts:emails> <contacts:emails> <contacts:email>falvarez@berkeley.edu</contacts:email> </contacts:emails> <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>
On success, a response with a "201 Created" HTTP status code will be returned:
Parameter | Meaning |
---|---|
HTTP Header Location | A URL of the form " |
Example
201 Created <url root>/bsp/contacts/urn:uuid:a451bee4-37fa-4064-a2d4-097b09b54d67
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 the data provided in the request is invalid |
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 |
500 | Internal Server Error | A service error prevented the resource from being returned |
A client requests a Bamboo Contact by submitting the contact's unique identifier (i.e. contactId)
Invoked as an HTTP GET method. Send an HTTP request of the form:
GET <url root>/bsp/contacts/{contactId} HTTP/1.1
Example:
GET <url root>/bsp/contacts/urn:uuid:ee1577a7-e66e-4c6c-81b2-7591f33365e0
Parameter | Meaning |
---|---|
contactId | Unique identifier for a Bamboo Contact |
On success, a response with a "200 OK" HTTP status code will be returned.
Parameter | Meaning |
---|---|
HTTP Body | An instance of a BambooContact XML document |
Example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <contacts:bambooContact 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: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-24T08:50:21.148-07:00</dcterms:created> <bsp:modifier>urn:uuid:99999999-9999-9999-9999-999999999999</bsp:modifier> <dcterms:modified xsi:type="dcterms:W3CDTF">2012-09-24T08:50:21.163-07:00</dcterms:modified> <contacts:contactId>urn:uuid:ee1577a7-e66e-4c6c-81b2-7591f33365e0</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>Mr. Fernando Alvarez Cadena PMP</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>
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the request:
Error (Status Code) | Meaning | Returned When |
---|---|---|
400 | Bad Request | reason specific to this service method for return of this error code, e.g., ParamA or ParamB are missing or zero-length |
401 | Unauthorized | reason specific to this service method for return of this error code, e.g., 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 credentialsd |
404 | Not Found | reason specific to this service method for return of this error code, e.g., A resource specified in this create request does not exist |
405 | Method Not Allowed | reason specific to this service method for return of this error code, e.g., Resource already exists |
500 | Internal Server Error | reason specific to this service method for return of this error code, e.g. (though not very informatively), A service error prevented the resource from being returned |
A client updates a Bamboo Contact by supplying both a Bamboo Contact Identifier and a valid BambooContact XML document. A minimum of one email account for the entity is required. Note that Update essentially replaces all of a contact's information, i.e. ommitting existing information from the XML submitted has the effect of deleting the information. If this is not the intent, read the contact first, and then submit that information +/- any deltas.
Invoked as an HTTP PUT method. Send an HTTP request of the form:
PUT <url root>/bsp/contacts/{contactId} HTTP/1.1
Parameter | Meaning |
---|---|
contactId | Unique identifier for a Bamboo Contact |
Example:
PUT <url root>/bsp/contacts/urn:uuid:28ae4ba0-40f2-4ccc-86f9-8577c29005a8
Example bambooContact XML document:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <contacts:bambooContact xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:contacts="http://projectbamboo.org/bsp/services/core/contact" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <contacts:contactId>urn:uuid:28ae4ba0-40f2-4ccc-86f9-8577c29005a8</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>Mr. Fernando Alvarez Cadena PMP</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>
On success, a response with a "200 OK" HTTP status code will be returned.
Parameter | Meaning |
---|---|
ParamA (e.g., HTTP Header Location) | description of returned value of ParamA |
ParamB (e.g., HTTP Body) | description of returned value of ParamB |
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the request:
Error (Status Code) | Meaning | Returned When |
---|---|---|
400 | Bad Request | reason specific to this service method for return of this error code, e.g., ParamA or ParamB are missing or zero-length |
401 | Unauthorized | reason specific to this service method for return of this error code, e.g., 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 | reason specific to this service method for return of this error code, e.g., A resource specified in this update request does not exist |
405 | Method Not Allowed | reason specific to this service method for return of this error code, e.g., Resource may not be updated |
500 | Internal Server Error | reason specific to this service method for return of this error code, e.g. (though not very informatively), A service error prevented the resource from being updated |
A client deletes a Bamboo Contact by supplying a Bamboo Contact Identifier.
Invoked as an HTTP DELETE method. Send an HTTP request of the form:
DELETE <url root>/bsp/contacts/{contactId} HTTP/1.1
Parameter | Meaning |
---|---|
contactId | Unique identifier for a Bamboo Contact |
Example:
DELETE <url root>/bsp/contacts/urn:uuid:ee1577a7-e66e-4c6c-81b2-7591f33365e0
On success, a response with a "200 OK" HTTP status code will be returned.
Parameter | Meaning |
---|---|
contactId | Unique identifier for a Bamboo Contact |
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the request:
Error (Status Code) | Meaning | Returned When |
---|---|---|
400 | Bad Request | reason specific to this service method for return of this error code, e.g., ParamA or ParamB are missing or zero-length |
401 | Unauthorized | reason specific to this service method for return of this error code, e.g., 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 | reason specific to this service method for return of this error code, e.g., A resource specified in this delete request does not exist |
405 | Method Not Allowed | reason specific to this service method for return of this error code, e.g., Resource may not be deleted |
500 | Internal Server Error | reason specific to this service method for return of this error code, e.g. (though not very informatively), A service error prevented the resource from being deleted |
See generated Javadoc for this service. Packages are org.projectbamboo.bsp.services.core.contact.*.