Purpose and Scope

Org Service currently performs three functions:

1. A relationship service - masters NODE, RELATION and RELATION_TYPE resources, and enables the maintenance and analysis of complex relations and directed graphs.
2. A group service - masters GROUP resources
3. A mechanism for remotely creating content in a hub - masters F_INTERESTGROUPS, F_MEMBERSHIPS and F_CONVS. This will be deprecated soon, and replaced by the relationship, group and content APIs.

Contents:

• Terminology
• Conventions and Return Codes
• Google Gadgets
• Schemas
• group
• groups
• f_interestgroup
• f_interestgroups
• relation
• relations
• recommendations
• API Guidelines
• Resource: GROUP
• Resource: GROUP_PUBLICATIONS
• Resource: GROUP_SUBSCRIPTIONS
• Resource: RELATION
• Resource: RELATION_TYPE
• Resource: RECOMMENDATION
• Resource: F_INTERESTGROUP (Deprecated)
• Resource: F_MEMBERSHIP (Deprecated)
• Resource: F_CONVS (Deprecated)

Terminology

Org Service uses the following terminology:

• Consumer - any application or service interacting with the nGen Platform.
• BSG RA GUID- aka BSG Reference Architecture Globally Unique Identifier. A unique string that identifies each consumer. BSG RA GUIDs have the form: 6b0c73c0-bsga-kali-rome-001b7744e04a. In the Ruby language you can produce a similarly formatted identifier using the UUIDTOOLS library command: UUID.timestamp_create().to_s.
• AUTH_USERNAME- The hub username, which is actually an email address. Note that this is used for convenience during early development, and will be replaced with AUTH_ID soon.
• Group/Interest Group/IG/F_INTERESTGROUP - an interchangeable term used to describe groups managed by the Org Service.
• Group Memberships - A user assignment to a group
• Section Tags - If the consumer supports displaying section tags for a group, all conversations with tags referenced by this element should appear in the tag's section.

.

Conventions and Return Codes

The API supports the nGen Platform conventions:

• Bad Request failures (e.g. supplying the wrong input parameters) returns HTTP code 400
• Authorization failures (e.g. using unknown user credentials) returns HTTP code 401
• Forbidden user (e.g. a user that has been banned) will return HTTP code 403
• Item Not Found failures (e.g. supplying an id for missing data) returns HTTP code 404
• Unsupported Service Invocations (e.g. using unsupported verbs or requesting an unsupported format - .xml/.html/etc) returns HTTP code 405
• Conflict failures(e.g. group name already exists when attempting to create group) will return HTTP code 409
• Internal Errors and other exceptions returns HTTP code 500
• As a general guideline, nGen Platforms services return appropriate HTTP codes wherever possible.

Schemas

• groups:

  <?xml version="1.0" encoding="UTF-8"?>
  <groups>
    <group>
      <id/> <!-- GUID -->
      <name/>
      <owner_id/> <!-- BSGRA_GUID of application that owns the group -->
      <owner_email/>
      <visibility/> <!-- Visibility of convs withing the group: [Public|Private] -->
      <membership_options/> <!-- [Open|Closed|Internal] -->
      <immutable/> <!-- boolean - whether the group is editable -->
      <deletable/> <!-- boolean - whether the group is deletable -->
      <rule/>
      <created_by/> <!-- ID of the user that created the group -->
      <created_at/> <!-- When was the group created? Format: 2008-10-21T20:35:00Z -->
      <updated_at/> <!-- When was the group last updated? Format: 2008-10-21T20:35:00Z -->
      <permalink/> <!-- Permanent URL that will always retrieve the group -->
      <member_count/> <!-- Integer - number of members in the group (i.e. http://staging1.kalivo.com/external_groups/show/363) -->
      <storage_guid/> <!-- GUID for the group avatar -->
      <storage_guid_small/> <!-- GUID for the small group avatar -->
      <owned_by_called/> <!-- true|false - is the group owned by the caller? -->
      <created_by_called/> <!-- true|false - was the group created by the caller? -->
      <!-- Optional attributes -->
      <description/>
      <private_description/>
      <num_of_convs_in_list/>
      <num_of_days_to_show/>
      <notify_on_request_invite/>
      <hide_group/> <!-- Group only visible to members -->
      <hide_group_members/> <!-- Membership list only visible to non-members -->
      <shared_group_ids/>
      <group_members_edit_allow/>
      <section_tags/>
      <show_participate_section/>
      <show_favorite_section/>
      <show_membership_section/>
      <!-- Optional attributes -->
      <membership>
        <member>
          <guid/> <!-- GUID of the member -->
          <name/> <!-- Name of the member -->
          <email/> <!-- Email address of the member -->
        </member>
        <member>
          <guid/>
          <name/>
          <email/>
        </member>
      </membership>
      <publications>
        <publication>
          <bsgra_guid/> <!-- GUID of application to which the group has been published -->
          <created_by/> <!-- GUID of the user that published the group -->
        <created_at/> <!-- Timestamp created when the group was published -->
        </publications>
        <publication>
          <bsgra_guid/>
        </publications>
        <publication>
          <bsgra_guid/>
        </publications>
      </publications>
    </group>
    <group>
      .
      .
      .
    </group>
  </groups>

• group:

  <?xml version="1.0" encoding="UTF-8"?>
  <group>
    <id/> <!-- GUID -->
    <name/>
    <owner_id/> <!-- BSGRA_GUID of application that owns the group -->
    <owner_email/>
    <visibility/> <!-- Visibility of convs withing the group: [Public|Private] -->
    <membership_options/> <!-- [Open|Closed|Internal] -->
    <immutable/> <!-- boolean - whether the group is editable -->
    <deletable/> <!-- boolean - whether the group is deletable -->
    <rule/>
    <created_by/> <!-- ID of the user that created the group -->
    <created_at/> <!-- When was the group created? Format: 2008-10-21T20:35:00Z -->
    <updated_at/> <!-- When was the group last updated? Format: 2008-10-21T20:35:00Z -->
    <permalink/> <!-- Permanent URL that will always retrieve the group -->
    <member_count/> <!-- Integer - number of members in the group (i.e. http://staging1.kalivo.com/external_groups/show/363) -->
    <storage_guid/> <!-- GUID for the group avatar -->
    <storage_guid_small/> <!-- GUID for the small group avatar -->
    <owned_by_called/> <!-- true|false - is the group owned by the caller? -->
    <created_by_called/> <!-- true|false - was the group created by the caller? -->
    <!-- Optional attributes -->
    <description/>
    <private_description/>
    <num_of_convs_in_list/>
    <num_of_days_to_show/>
    <notify_on_request_invite/>
    <hide_group/> <!-- Group only visible to members -->
    <hide_group_members/> <!-- Membership list only visible to non-members -->
    <shared_group_ids/>
    <group_members_edit_allow/>
    <section_tags/>
    <show_participate_section/>
    <show_favorite_section/>
    <show_membership_section/>
    <!-- Optional attributes -->
    <membership>
      <member>
        <guid/> <!-- GUID of the member -->
        <name/> <!-- Name of the member -->
        <email/> <!-- Email address of the member -->
      </member>
      <member>
        <guid/>
        <name/>
        <email/>
      </member>
    </membership>
    <publications>
      <publication>
        <bsgra_guid/> <!-- GUID of application to which the group has been published -->
        <created_by/> <!-- GUID of the user that published the group -->
      <created_at/> <!-- Timestamp created when the group was published -->
      </publications>
      <publication>
        <bsgra_guid/>
      </publications>
      <publication>
        <bsgra_guid/>
      </publications>
    </publications>
  </group>

• f_interestgroups:

  <?xml version="1.0" encoding="UTF-8"?>
  <f_interestgroups>
    <f_interestgroup>
      <id/> <!-- GUID -->
      <name/>
      <owner_id/> <!-- BSGRA_GUID of application that owns the group -->
      <owner_email/>
      <visibility/> <!-- Visibility of convs withing the group: [Public|Private] -->
      <membership_options/> <!-- [Open|Closed|Internal] -->
      <immutable/> <!-- boolean - whether the group is editable -->
      <deletable/> <!-- boolean - whether the group is deletable -->
      <rule/>
      <created_by/> <!-- ID of the user that created the group -->
      <created_at/> <!-- When was the group created? Format: 2008-10-21T20:35:00Z -->
      <updated_at/> <!-- When was the group last updated? Format: 2008-10-21T20:35:00Z -->
      <permalink/> <!-- Permanent URL that will always retrieve the group -->
      <member_count/> <!-- Integer - number of members in the group (i.e. http://staging1.kalivo.com/external_groups/show/363) -->
      <storage_guid/> <!-- GUID for the group avatar -->
      <storage_guid_small/> <!-- GUID for the small group avatar -->
      <owned_by_called/> <!-- true|false - is the group owned by the caller? -->
      <created_by_called/> <!-- true|false - was the group created by the caller? -->
      <!-- Optional attributes -->
      <description/>
      <private_description/>
      <num_of_convs_in_list/>
      <num_of_days_to_show/>
      <notify_on_request_invite/>
      <hide_group/> <!-- Group only visible to members -->
      <hide_group_members/> <!-- Membership list only visible to non-members -->
      <shared_group_ids/>
      <group_members_edit_allow/>
      <section_tags/>
      <show_participate_section/>
      <show_favorite_section/>
      <show_membership_section/>
      <!-- Optional attributes -->
      <membership>
        <member>
          <guid/> <!-- GUID of the member -->
          <name/> <!-- Name of the member -->
          <email/> <!-- Email address of the member -->
        </member>
        <member>
          <guid/>
          <name/>
          <email/>
        </member>
      </membership>
      <publications>
        <publication>
          <bsgra_guid/> <!-- GUID of application to which the group has been published -->
          <created_by/> <!-- GUID of the user that published the group -->
        <created_at/> <!-- Timestamp created when the group was published -->
        </publications>
        <publication>
          <bsgra_guid/>
        </publications>
        <publication>
          <bsgra_guid/>
        </publications>
      </publications>
    </f_interestgroup>
    <f_interestgroup>
      .
      .
      .
    </f_interestgroup>

• f_interestgroup:

  <?xml version="1.0" encoding="UTF-8"?>
  <f_interestgroup>
    <id/> <!-- GUID -->
    <name/>
    <owner_id/> <!-- BSGRA_GUID of application that owns the group -->
    <owner_email/>
    <visibility/> <!-- Visibility of convs withing the group: [Public|Private] -->
    <membership_options/> <!-- [Open|Closed|Internal] -->
    <immutable/> <!-- boolean - whether the group is editable -->
    <deletable/> <!-- boolean - whether the group is deletable -->
    <rule/>
    <created_by/> <!-- ID of the user that created the group -->
    <created_at/> <!-- When was the group created? Format: 2008-10-21T20:35:00Z -->
    <updated_at/> <!-- When was the group last updated? Format: 2008-10-21T20:35:00Z -->
    <permalink/> <!-- Permanent URL that will always retrieve the group -->
    <member_count/> <!-- Integer - number of members in the group (i.e. http://staging1.kalivo.com/external_groups/show/363) -->
    <storage_guid/> <!-- GUID for the group avatar -->
    <storage_guid_small/> <!-- GUID for the small group avatar -->
    <owned_by_called/> <!-- true|false - is the group owned by the caller? -->
    <created_by_called/> <!-- true|false - was the group created by the caller? -->
    <!-- Optional attributes -->
    <description/>
    <private_description/>
    <num_of_convs_in_list/>
    <num_of_days_to_show/>
    <notify_on_request_invite/>
    <hide_group/> <!-- Group only visible to members -->
    <hide_group_members/> <!-- Membership list only visible to non-members -->
    <shared_group_ids/>
    <group_members_edit_allow/>
    <section_tags/>
    <show_participate_section/>
    <show_favorite_section/>
    <show_membership_section/>
    <!-- Optional attributes -->
    <membership>
      <member>
        <guid/> <!-- GUID of the member -->
        <name/> <!-- Name of the member -->
        <email/> <!-- Email address of the member -->
      </member>
      <member>
        <guid/>
        <name/>
        <email/>
      </member>
    </membership>
    <publications>
      <publication>
        <bsgra_guid/> <!-- GUID of application to which the group has been published -->
        <created_by/> <!-- GUID of the user that published the group -->
  *    <created_at/> <!-- Timestamp created when the group was published -->
      </publications>
      <publication>
        <bsgra_guid/>
      </publications>
      <publication>
        <bsgra_guid/>
      </publications>
    </publications>
  </f_interestgroup>

• relation:

  <?xml version="1.0" encoding="UTF-8"?>
  <relation>
    <relation_type>
      <created_by>334e7072-51c5-11dd-b018-0030488b5524</created_by>
      <guid>13d7ddb6-e836-11dd-af90-0019d1251904</guid>
      <name>has member</name>
      <usage_count type="integer">9507</usage_count>
    </relation_type>
    <l_ref>
      <node>
      <guid>b9182e40-ef05-11dd-b8b1-0019d1039198</guid>
      <ref_guid>b8c1c758-ef05-11dd-92df-0019d16d4e11</ref_guid>
      <ref_provision>service_org_groups</ref_provision>
      </node>
    </l_ref>
    <r_ref>
      <node>
        <guid>e5bdfd10-eef3-11dd-bc41-0019d1039198</guid>
        <ref_guid>675d6ff4-c0aa-11dd-a454-0019d1039198</ref_guid>
        <ref_provision>service_user</ref_provision>
      </node>
    </r_ref>
  </relation>

• relations:

  <?xml version="1.0" encoding="UTF-8"?>
  <relations>
    <relation/>
    <relation/>
    <relation/>
      .
      .
      .
    <relation/>
    <message/>
    <message/>
    <message/>
      .
      .
      .
    <message/>
  </relations>

• recommendations:

  <?xml version="1.0" encoding="UTF-8"?>
  <recommendations>
    <user>
      <name/>
      <guid/>
      <provision/>
      <strength/>
      <profile/>
      <updated_at/>
    </user>
    <user>
      <name/>
      <guid/>
      <provision/>
      <strength/>
      <profile/>
      <updated_at/>
    </user>
      .
      .
      .
    <user>
      <name/>
      <guid/>
      <provision/>
      <strength/>
      <profile/>
      <updated_at/>
    </user>
  </recommendations>

API Guidelines

• All methods in the API require the following parameters be passed in either as a request header or a request parameter:

  Header	Parameter	Description
  BSGRA_GUID	bsra_guid	bsgra_guid value appropriate to your consumer service.
  AUTH_SESSION_INDEX	auth_session_index	The authentication token of the originating session.
  - or -
  AUTH_USERNAME	auth_username	The email address of the user performing request.

• All dates passed/returned by the API should adhere to ISO 8601 standard. Also, all dates returned by API will be in UTC time.

GROUP Resource

A GROUP resource represents an nGen Collab group.

• POST /groups
  Create a new group
  • Notes:
    • Expects a parameter named 'group' that looks like this:

      <?xml version="1.0" encoding="UTF-8"?>
      <group>
        <name>MyInterestGroup</name>
        <rule>rule</rule>
        <immutable>true|false</immutable>
        <deletable>true|false</deletable>
        <visibility>Public</visibility>
        <membership></membership>
        <tag_with></tag_with>
        <storage_guid>b4c5fe16-401e-4d09-b646-f20355448d4b</storage_guid>
        <storage_guid_small>a4aeaec7-832d-46fc-bf09-d9c02f3997a8</storage_guid_small>
        <description>A public description of the group</description>
        <section_tags>Section1,Section2</section_tags>
        <extended_group_attributes>YAML</extended_group_attributes>
      </group>

  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID
      • missing group parameter
    • 401 Unauthorized - invalid AUTH_SESSION_INDEX or AUTH_USERNAME header
    • 409 Conflict - group name already exists.
    • 500 Internal Error server_side exception
    • 201 Success - returns an instance of the group schema.


• PUT /groups/<group_id>
  Update a Group, from a passed in block of group xml. Parameter name for the xml is 'group'.
  • Notes:
    • Multi-word section tags must be surrounded with double quotes.
    • Expects a parameter named 'group' that looks like this:

      <?xml version="1.0" encoding="UTF-8"?>
      <group>
        <name>MyInterestGroup</name>
        <rule>rule</rule>
        <immutable>true|false</immutable>
        <deletable>true|false</deletable>
        <visibility>Public</visibility>
        <membership></membership>
        <tag_with></tag_with>
        <storage_guid>b4c5fe16-401e-4d09-b646-f20355448d4b</storage_guid>
        <storage_guid_small>a4aeaec7-832d-46fc-bf09-d9c02f3997a8</storage_guid_small>
        <description>A public description of the group</description>
        <section_tags>Section1,Section2</section_tags>
        <extended_group_attributes>YAML</extended_group_attributes>
      </group>

  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID
      • missing group parameter
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME
    • 403 Forbidden - user is not authorized to edit the Group
    • 404 Not Found - group is not found
    • 500 Internal Error - server-side exception
    • 200 Success


• PUT /group_publications/<group_id>
  Update the publications for a group
  • Notes:
    • Expects a parameter named 'publications' that looks like this:

      <?xml version="1.0" encoding="UTF-8"?>
      <publications>
        <publication>
          <bsgra_guid>application_id_1</bsgra_guid>
          <created_by>user_guid_1</created_by>
        </publication>
        <publication>
          <bsgra_guid>application_id_2</bsgra_guid>
          <created_by>user_guid_2</created_by>
        </publication>
      </publications>

  • Responses:
    • Bad Request: 400 -
      • missing BSGRA_GUID
      • missing publications parameter
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME
    • 403 Forbidden - user is not authorized to edit the Group
    • 404 Not Found - group_id is not found.
    • 500 Internal Error - server-side exception
    • 200 Success


• DELETE /groups/<group_id>
  Delete a group by its <group_id>
  • Responses:
    • 400 Bad Request - missing BSGRA_GUID
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME
    • 403 Forbidden - user is not authorized to delete the Group
    • 404 Not Found - unrecognized group_id
    • 500 Internal Error - server-side exception
    • 200 Success


• GET /groups
  Returns all groups accessible by the consumer
  • Notes:
    • This call can be made anonymously - in which case only unhidden groups will be returned, or it can be made authenticated, in which case group security rules will be applied and the appropriate set of groups returned. If invalid credentials are supplied, the call will currently return 401 Unauthorized. This behavior will change in the near future to act as an anonymous request and return a 200 Success.
  • Filters:
    • originator - the BSGRA_GUID of the application that originated the group (i.e. the group's home)
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID
      • missing group parameter
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME header.
    • 500 Internal Error - server-side error
    • 200 Success - returns an instance of the groups schema.


• GET /groups/<group_id>
  Returns the Group matching the <group_id>
  • Notes:
    • Publication data will only be available if the request comes from the originating bsgra_guid
  • Responses:
    • 400 Bad Request - missing BSGRA_GUID
    • 401 Unauthorized - in case of an invalid or absent AUTH_SESSION_INDEX or AUTH_USERNAME header.
    • 500 Internal Error - server-side error
    • 200 Success - returns an instance of the group schema.

GROUP_PUBLICATIONS Resource

A resource representing a publication of a group.

• GET /group_publications
  Returns a list of published groups, based on the BSGRA_GUID header.
  • Responses:
    • 400 Bad Request - missing BSGRA_GUID
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME
    • 403 Forbidden - user is not authorized to see the publication list
    • 200 Success - returns:

      <?xml version="1.0" encoding="UTF-8"?>
      <publications>
        <publication>
          <owner_id>bb52c580-9faf-11dd-8fbd-001d09a5d9db</owner_id>
          <group_id>e739a7b6-b64b-11dc-8d54-0030488b5524</group_id>
          <group_name>Developer Updates</group_name>
        <publication>
      </publications

GROUP_SUBSCRIPTIONS Resource

A resource representing a subscription to a published group.

• GET /group_subscriptions
  Returns a list of subscriptions, based on the BSGRA_GUID header.
  • Responses:
    • 400 Bad Request - missing BSGRA_GUID
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME
    • 403 Forbidden - user is not authorized to see the subscription list
    • 200 Success - returns:

      <?xml version="1.0" encoding="UTF-8"?>
      <subscriptions>
        <subscription>
          <owner_id>bb52c580-9faf-wwww-wwww-001d09a5d9db</owner_id>
          <group_id>e739a7b6-b64b-xxxx-xxxx-0030488b5524</group_id>
          <group_name>Group 1</group_name>
        <subscription>
        <subscription>
          <owner_id>bb52c580-9faf-yyyy-yyyy-001d09a5d9db</owner_id>
          <group_id>e739a7b6-b64b-zzzz-zzzz-0030488b5524</group_id>
          <group_name>Group 2</group_name>
        <subscription>
      </subscriptions>



• POST /group_subscriptions
  Overwrites the existing subscription set with the new one
  • Bad Request: 400, if mandatory headers not passed.
  • Unauthorized: 401, in case of an invalid or absent AUTH_SESSION_INDEX or AUTH_USERNAME header.
  • Forbidden: 403, if user is not authorized to create a subscription.
  • Not Found: 404, if any group group_id is not found or not published.
  • Internal Error: 500, if an unexpected error occurs.
  • Success: 200. The expected XML request parameter 'subscriptions':

    <?xml version="1.0" encoding="UTF-8"?>
    <subscriptions>
      <subscription>
        <group_id>group_id_1</group_id>
      </subscription>
      <subscription>
        <group_id>group_id_2</group_id>
      </subscription>
    </subscriptions>

  • No value is returned.
  • Note: all subscriptions must be valid or the entire call will fail


• POST /group_subscriptions/group_id
  Creates a subscription to a published group for the application making the request.
  • Bad Request: 400, if mandatory headers or group_id parameter not passed.
  • Unauthorized: 401, in case of an invalid or absent AUTH_SESSION_INDEX or AUTH_USERNAME header.
  • Forbidden: 403, if user is not authorized to create a subscription.
  • Not Found: 404, if group group_id is not found or not published.
  • Internal Error: 500, if an unexpected error occurs.
  • Success: 200.
  • No value is returned.


• DELETE /group_subscriptions/group_id
  Cancels a subscription to a published group for the application making the request.
  • Bad Request: 400, if BSGRA_GUID header or group_id parameter not passed.
  • Unauthorized: 401, in case of an invalid or absent AUTH_SESSION_INDEX or AUTH_USERNAME header.
  • Forbidden: 403, if user is not authorized to delete a subscription.
  • Not Found: 404, if group group_id not found, or not published.
  • Internal Error: 500, if an unexpected error occurs.
  • Success: 200.
  • No value is returned.

RELATIONS Resource

A resource representing a directed relationship between two entities. The relationship is modeled as ENTITY_1 => RELATIONSHIP => ENTITY_2. Because the relationships are 'directed,' they are not reversible. Examples:

• JOHN => MEMBER OF => MARKETING
• PETER => FRIEND OF => SUSAN
• WESTERN PETROLEUM => SUBSIDIARY OF => NORTHERN OIL

Because the ENTITY is treated polymorphically, they may be nested. John can be a FRIEND OF Peter, and Peter a FRIEND OF Mary. That gives John a second-order relationship to Mary. This kind of relationship graphing can be used to facilitate social graph and party model implementations.

• GET /relations
  Returns the set of relations satisfying the input parameters.
  • Notes:
  • Results will be paged in the near future to protect the server
  • Accepts the following parameters in any combination:
    • l_ref_guid: the 'left' entity (i.e. All of JOHN's relations)
    • relation_type (name or id): the relationship (i.e. MEMBER OF, REPORTS TO, FAVORITED)
    • r_ref_guid: the 'right' entity (i.e. All relations to PETER)
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID header
      • missing all of the three option parameters listed above - it is required that at least one be present
    • 200 Success - returns an instance of the relations schema, containing one or more instances of the relation schema.


• POST /relations
  Create one or more relations.
  • Notes:
  • Accepts the following optional parameter:
    • increment_strength: If an existing relation is found, instead of throwing an error, increment the strength of this relation by 1.
  • Expects either a parameter named relation that conforms to this schema:

    <?xml version="1.0" encoding="UTF-8"?>
    <relation>
      <left_ref/>
      <left_provision/>
      <relation_type/>
      <right_ref/>
      <right_provision/>
    </relation>

    or a parameter named relations that accepts multiple relations thusly:

    <?xml version="1.0" encoding="UTF-8"?>
    <relations>
      <relation>
        <left_ref/>
        <left_provision/>
        <relation_type/>
        <right_ref/>
        <right_provision/>
      </relation>
      <relation>
      .
      .
      .
      </relation>
    </relations>

  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID header
      • missing the mandatory relation|relations parameter
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME header.
    • 409 Conflict - if the relation already exists and increment_strength is not set.
    • 500 Internal Error - if an unexpected error occurs.
    • 201 Created - returned upon success by the single-relation form of the command, along with an instance of the relation schema.
    • 200 Success - returned upon success by single-relation if the relation already existed with incrment_strength, or by the multiple-relation form of the command, along with an instance of the relations schema. A 200 in no way guarantees that any relations were successfully created - only that the command was parsed and processed without incident. The only way to know whether any individual relation was actually processed is to examine the return value for the call, which will include only relations that were successdully created. Forensic messages are allowed by the schema, and will provide some reason as to why a given relation failed to post.


• DELETE /relations
  Remove one or more relations.
  • Notes:
  • Accepts the following parameters in any combination:
    • l_ref_guid: the 'left' entity (i.e. All of JOHN's relations)
    • relation_type (name or id): the relationship (i.e. MEMBER OF, REPORTS TO, FAVORITED)
    • r_ref_guid: the 'right' entity (i.e. All relations to PETER)
    • decrement_strength: If an existing relation is found, and its strength is greater than 1, instead of deleting it, reduce its strength by 1, otherwise delete as usual.
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID header
      • missing all of the three option parameters listed above - it is required that at least one be present
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME header.
    • 500 Internal Error - if an unexpected error occurs.
    • 200 Success - indicates that the relations were deleted successfully.

RELATION_TYPES Resource

An embedded resource representing the nature of the relationship between two parties in a RELATION resource.

TBD.

RECOMMENDATION Resource

A transient, read-only resource representing a list of resources collected and organized by their similarity to another resource. This resource is used to gather data such as "Content You Might Be Interested In", "Meetings You Should Attend" or "Users You Should Meet"

• GET /recommendations?type=<type>&id=<id>&provision=<provision>
  Get a list of resources that are similar to the provided resource
  • Notes:
    • type
    - the target resource type. Currently, the only supported value is 'user' (i.e. users a user should meet.) In the near future, we'll support 'group' as well (i.e. groups you should be a member of.) We will never support 'content' because content is mastered in a different service (the content service) and that service will be responsible for generating those recommendations (although it will seed it's algorithms with the results from this service's "users you should care about" algorithms.
    • provision
    - the provision name of the source resource. Defaults to 'service_user' if either provision or id is not provided.
    • id - the id of the source resource. Defaults to the guid of the user making the call.
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID header
      • unrecognized id parameter
      • invalid type parameter
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME header.
    • 500 Internal Error - if an unexpected error occurs.
    • 200 Success - returns an instance of the recommendations schema.

F_INTERESTGROUP Resource

An F_INTERESTGROUP resource is a proxy for an GROUP resource, and will eventually be deprecated.

• POST /f_interestgroups
  Create a new Interest Group
  • Notes:
    • All groups created via this call are mutable and deletable.
    • Expects a parameter named 'group' that looks like this:

      <?xml version="1.0" encoding="UTF-8"?>
      <f_interestgroup>
        <name/>
        <owner_id/> <!-- defaults to the BSGRA_GUID of the caller, but can be overridden -->
        <created_by/> <!-- defaults to the ID of the caller, but can be overridden -->
        <owner_email/>
        <visibility/> <!-- Visibility of convs withing the group: [Public|Private] -->
        <membership_options/> <!-- [Open|Closed|Internal] -->
        <rule/>
        <created_at/> <!-- When was the group created? Format: 2008-10-21T20:35:00Z -->
        <updated_at/> <!-- When was the group last updated? Format: 2008-10-21T20:35:00Z -->
        <permalink/> <!-- Permanent URL that will always retrieve the group -->
        <member_count/> <!-- Integer - number of members in the group (i.e. http://staging1.kalivo.com/external_groups/show/363) -->
        <storage_guid/> <!-- GUID for the group avatar -->
        <storage_guid_small/> <!-- GUID for the small group avatar -->
        <owned_by_called/> <!-- true|false - is the group owned by the caller? -->
        <created_by_called/> <!-- true|false - was the group created by the caller? -->
        <description/>
        <private_description/>
        <num_of_convs_in_list/>
        <num_of_days_to_show/>
        <notify_on_request_invite/>
        <hide_group/> <!-- Group only visible to members -->
        <hide_group_members/> <!-- Membership list only visible to non-members -->
        <shared_group_ids/>
        <group_members_edit_allow/>
        <section_tags/>
        <show_participate_section/>
        <show_favorite_section/>
        <show_membership_section/>
      </f_interestgroup>

  • Responses
    • 400 Bad Request -
      • missing BSGRA_GUID header
      • missing group parameter
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME header.
    • 403 Forbidden - if user is not authorized to create a group.
    • 409 Conflict - if the group name already exists.
    • 500 Internal Error - if an unexpected error occurs.
    • 200 Success - returns an instance of the f_interestgroup schema.


• PUT /f_interestgroups/<group_id>
  Update an Interest Group
  • Notes
    • Expects a parameter named 'group' that looks like this:

      <?xml version="1.0" encoding="UTF-8"?>
      <f_interestgroup>
        <name>MyUpdatedGroup</name>
        <description>&lt;p&gt;My Updated Group Description&lt;/p&gt;</description>
        <section_tags>Section1, &quot;Section 2&quot;, &quot;Section 3&quot;</section_tags>
      </f_interestgroup>

  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID
      • missing group parameter
      • Badly-formed group parameter
      • group is immutable
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME header.
    • 403 Forbidden - user is not authorized to edit the Interest Group
    • 404 Not Found -
      • unrecognized AUTH_USERNAME
      • unrecognized group
    • 500 Internal Error server-side error
    • 200 Success


• PUT /f_interestgroups/<group_id>
  Update the publications for an interest group
  • Notes
    • Expects a parameter named 'publications' that looks like this:

      <?xml version="1.0" encoding="UTF-8"?>
      <publications>
        <publication>
          <bsgra_guid>&lt;i&gt;Application ID 1&lt;/i&gt;</bsgra_guid>
          <created_by>&lt;i&gt;User 1 GUID&lt;/i&gt;</created_by>
        </publication>
        <publication>
          <bsgra_guid>&lt;i&gt;Application ID 2&lt;/i&gt;</bsgra_guid>
          <created_by>&lt;i&gt;User 2 GUID&lt;/i&gt;</created_by>
        </publication>
      </publications>

  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID
      • missing publications parameter
      • badly-formed publications parameter
      • group is immutable
    • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME header.
    • 403 Forbidden - user is not authorized to edit Interest Group
    • 404 Not Found -
      • unrecognized AUTH_USERNAME
      • unrecognized group
  • 500 Internal Error - server-side error
  • 200 Success

DELETE /f_interestgroups/<group_id>
Delete a group by its <group_id>

• Responses:
  • 400 Bad Request - missing BSGRA_GUID
  • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME header.
  • 403 Forbidden -
    • user is not authorized to delete the group
    • group is not deletable
  • 404 Not Found -
    • unrecognized AUTH_USERNAME
    • unrecognized group
  • 500 Internal Error server-side error
  • 200 Success

GET /f_interestgroups
Returns all groups accessible by the consumer

• Filters:
  • originator - the BSGRA_GUID of the application that originated the group (i.e. the group's home)
• Responses:
  • 400 Bad Request -
    • missing BSGRA_GUID
    • missing group parameter
  • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME header.
  • 500 Internal Error - server-side error
  • 200 Success - returns an instance of the f_interestgroups schema.

GET /f_interestgroups/<group_id>
Returns the Group matching the <group_id>.

• Notes:
  • Publication data will only be available if the request comes from the originating bsgra_guid
• Responses:
  • 400 Bad Request - missing BSGRA_GUID
  • 401 Unauthorized - unrecognized AUTH_SESSION_INDEX or AUTH_USERNAME header.
  • 404 Not Found - unrecognized group_id
  • 500 Internal Error - server-side exception
  • 200 Success - returns an instance of the f_interestgroup schema.

F_MEMBERSHIPS Resource

An F_MEMBERSHIPS resource represents user assignments to groups

• POST /f_memberships
  Create a new Group Membership, from a passed in block of group membership xml. Parameter name for th xml is 'membership'.
  • Notes:
    • Expects a parameter named 'membership' that looks like this:

      <?xml version="1.0" encoding="UTF-8"?>
      <f_membership>
        <group>bb52c580-9faf-11dd-8fbd-001d09a5d9db</group>
        <entity>mroeder@ngenera.com</entity>
      </f_membership>

  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID or AUTH_USERNAME
      • missing required parameter 'membership'
      • badly-formed or invalid XML in parameter 'membership'
    • 403 Forbidden - user not authorized to edit Group
    • 404 Not Found -
      • unrecognized AUTH_USERNAME
      • unrecognized group
      • unrecognized user
    • 500 Internal Error - if an unexpected error occurs.
    • 200 Success returns:

      <?xml version="1.0" encoding="UTF-8"?>
      <f_membership>
        <group>bb52c580-9faf-11dd-8fbd-001d09a5d9db</group>
        <entity>e739a7b6-b64b-11dc-8d54-0030488b5524</entity>
      </f_membership>

• DELETE /f_memberships/<group_id>/<user_id>
  Revoke a Group Membership
  • Responses:
    • 400 Bad Request - missing BSGRA_GUID or AUTH_SESSION_INDEX/AUTH_USERNAME
    • 403 Forbidden - user is not authorized to change group membership
    • 404 Not Found -
      • unrecognized AUTH_USERNAME
      • unrecognized group
      • user is not a member of the group
    • 500 Internal Error - server-side error
    • 200 Success

F_CONVS Resource

An F_CONVS resource is a wrapper for a CONV resource, representing a wiki or a reply.

• POST /f_convs
  Create a new conversation from a passed in block of group xml.
  • Notes:
    • Expects parameter named 'conv':

      <?xml version="1.0" encoding="UTF-8"?>
      <f_conv>
        <type/> <!-- REQUIRED: conv | wiki | poll -->
        <subject/> <!-- UNIQUE, DEFAULT: copy of body -->
        <body/> <!-- REQUIRED - Max Length 150K -->
        <parent/> <!-- DEFAULT: 0 (Root) -->
        <tag_list/> <!-- OPTIONAL: "tag 1", tag2, "tag 3" -->
        <allow_comments/> <!-- OPTIONAL, BOOLEAN, DEFAULT: false -->
        <alert_on_replies/> <!-- OPTIONAL, BOOLEAN, DEFAULT: false -->
      </f_conv>

    • To assign a conversation to a group, provide the group name in the tag_list.
    • To create a reply, specify the ID of the parent conversation in the parent element.
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID or AUTH_USERNAME
      • missing or badly-formed conv parameter
    • 404 Not Found -
      • unrecognized AUTH_USERNAME
    • 500 Internal Error if an unexpected error occurs.
    • 200 Success - For a regular conv, returns:

      <?xml version="1.0" encoding="UTF-8"?>
      <conv>
        <id/>
        <guid/>
        <type/>
        <subject/>
        <body/>
        <ip/>
        <tag_list/>
        <reply_count/>
        <parent/>
        <created_at/>
        <published_at/>
        <updated_at/>
        <name/>
        <permalink/>
        <allow_comments/>
        <alert_on_replies/>
        <email/>
      </conv>

      For a poll, returns:

      <?xml version="1.0" encoding="UTF-8"?>
      <conv>
        <id/>
        <guid/>
        <type/>
        <subject/>
        <body/>
        <ip/>
        <tag_list/>
        <reply_count/>
        <parent/>
        <created_at/>
        <published_at/>
        <updated_at/>
        <name/>
        <permalink/>
        <allow_comments/>
        <alert_on_replies/>
        <email/>
        <answers>
          <answer/>
        </answers>
        <responses>
          <response/>
        </responses>
        <answer_type/>
        <allow_write_in/>
        <results_view/>
        <close_date/>
      </conv>

• PUT /f_convs/<conv_id>
  Update a conversation from a passed in block of conv xml. Parameter name for the xml is 'conv'.
  • Notes:
    • Expects parameter 'conv':

      <?xml version="1.0" encoding="UTF-8"?>
      <f_conv>
        <subject/>
        <body/> <!-- Max Length 150K -->
        <tag_list/> <!-- i.e. "tag 1", tag2, "tag 3" -->
        <allow_comments/> <!-- true | false -->
        <alert_on_replies/> <!-- true | false -->
      </f_conv>

    • To assign a conversation to a group, provide the group name in the tag_list.
    • To create a reply, specify the ID of the parent conversation in the parent element.
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID or AUTH_USERNAME
      • missing conv_id
      • missing conv parameter
      • badly-formed XML in conv parameter
    • 403 Forbidden - user is not allowed to edit the conversation in question
    • 404 Not Found -
      • unrecognized AUTH_USERNAME
      • unrecognized conv_id
    • 500 Internal Error - server-side error
    • 200 Success - no body in response


• DELETE /f_convs/<conv_id>
  Delete a Conversation
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID or AUTH_USERNAME
      • conv_id not passed.
    • 403 Forbidden - user is not allowed to delete the conversation.
    • 404 Not Found -
      • unrecognized AUTH_USERNAME
      • unrecognized conv_id
    • 500 Internal Error - server-side error
    • 200 Success - no body in response


• GET /f_convs?tag=<tag> and /f_convs?group=<group_id> and /f_convs?owner=<user_email>
  Returns all root and orphaned conversations assigned to the passed in tags, groups, users ownership.
  • Filters include the following query string parameters:
    • owner - find by the conversation creator - ?owner=<owner email>
    • group - ?group=<group_id>. Specify multiple groups with group[]=<group1_id>&group[]=<group2_id>
    • tag - ?tag=<tag>. Specify multiple tags with tag[]=<Tag1>&tag[]=<Tag2>
    • created_at - Use iso8601 formatted date time. Filters so only conversations created after specified time are returned.
    • limit - Limits number of conversations returned. Defaults to 10.
    • offset - Starts first conversation returned at the specified offset. Defaults to 1.
  • Headers returned:
    • LIMIT - The used limit parameter
    • OFFSET - The used offset parameter
    • TOTAL - The total amount of conversations found (regardless of limit/offset)
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID or AUTH_USERNAME
      • missing all of [group_id / conv_id / tag / owner] - at least one must be provided
      • unrecognized group_id
      • offset < 1
    • 404 Not Found - unrecognized AUTH_USERNAME
    • 500 Internal Error - server-side error
    • 200 Success. Returns:

      <?xml version="1.0" encoding="UTF-8"?>
      <f_convs>
        <f_conv>
          <id>1507</id>
          <type>Conv</type>
          <subject>My Subject</subject>
          <body>My Conversation Body</body>
          <tag_list>MyInterestGroup</tag_list>
          <reply_count>1</reply_count>
          <parent>0</parent>
          <created_at>2008-09-09T18:05:33Z</created_at>
          <published_at>2008-09-09T18:06:47Z</published_at>
          <updated_at>2008-10-24T21:09:51Z</updated_at>
          <name>Jonathan Bell</name>
          <allow_comments>true|false</allow_comments>
          <alert_on_replies>true|false</alert_on_replies>
          <email>JBell@ngenera.com</email>
        </f_conv>
        <f_conv>
          <id>1514</id>
          <type>Conv</type>
          <subject>Test Subject</subject>
          <body>Test Body</body>
          <tag_list>Test</tag_list>
          <reply_count>0</reply_count>
          <parent>0</parent>
          <created_at>2008-09-30T18:05:33Z</created_at>
          <published_at>2008-09-30T18:06:47Z</published_at>
          <updated_at>2008-10-24T21:09:51Z</updated_at>
          <name>Jonathan Bell</name>
          <allow_comments>true|false</allow_comments>
          <alert_on_replies>true|false</alert_on_replies>
          <email>JBell@ngenera.com</email>
        </f_conv>
      </f_convs>

• GET /f_convs/<conv_id>
  Returns a conversation (root or reply) and all of its children.
  • Filters include the following query string parameters:
    • owner - find by the conversation creator - ?owner=<owner email>
    • group - ?group=<group_id>. Specify multiple groups with group[]=<group1_id>&group[]=<group2_id>
    • tag - ?tag=<tag>. Specify multiple tags with tag[]=<Tag1>&tag[]=<Tag2>
    • created_at - Use iso8601 formatted date time. Filters so only conversations created after specified time are returned.
    • limit - Limits number of conversations returned. Defaults to 10.
    • offset - Starts first conversation returned at the specified offset. Defaults to 1.
  • Headers returned:
    • LIMIT - The used limit parameter
    • OFFSET - The used offset parameter
    • TOTAL - The total number of conversations found (independent of limit/offset)
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID or AUTH_USERNAME
      • missing all of [group_id / conv_id / tag / owner] - at least one must be provided
      • Unrecognized group_id
      • offset < 1
    • 404 Not Found - unrecognized AUTH_USERNAME
    • 500 Internal Error - server-side error
    • 200 Success - response:

      <?xml version="1.0" encoding="UTF-8"?>
      <f_convs>
        <f_conv>
          <id>1507</id>
          <type>Conv</type>
          <subject>My Subject</subject>
          <body>My Conversation Body</body>
          <tag_list>MyInterestGroup</tag_list>
          <reply_count>1</reply_count>
          <parent>0</parent>
          <created_at>2008-09-09T18:05:33Z</created_at>
          <published_at>2008-09-09T18:06:47Z</published_at>
          <updated_at>2008-10-24T21:09:51Z</updated_at>
          <name>Jonathan Bell</name>
          <allow_comments>true|false</allow_comments>
          <alert_on_replies>true|false</alert_on_replies>
          <email>JBell@ngenera.com</email>
        </f_conv>
        <f_conv>
          <id>1508</id>
          <type>Conv</type>
          <subject>RE: My Subject</subject>
          <body>My reply</body>
          <tag_list></tag_list>
          <reply_count>0</reply_count>
          <parent>1507</parent>
          <created_at>2008-09-30T18:05:33Z</created_at>
          <published_at>2008-09-30T18:06:47Z</published_at>
          <updated_at>2008-10-24T21:09:51Z</updated_at>
          <name>Jonathan Bell</name>
          <allow_comments>true|false</allow_comments>
          <alert_on_replies>true|false</alert_on_replies>
          <email>JBell@ngenera.com</email>
        </f_conv>
      </f_convs>

• HEAD /f_convs
  Returns counts of all root and orphaned conversations assigned to the passed in tags, groups, and users ownership.
  • Filters include the following query string parameters:
    • owner - find by the conversation creator - ?owner=<owner email>
    • group - ?group=<group_id>. Specify multiple groups with group[]=<group1_id>&group[]=<group2_id>
    • tag - ?tag=<tag>. Specify multiple tags with tag[]=<Tag1>&tag[]=<Tag2>
    • created_at - Use iso8601 formatted date time. Filters so only conversations created after specified time are returned.
    • limit - Limits number of conversations returned. Defaults to 10.
    • offset - Starts first conversation returned at the specified offset. Defaults to 1.
  • Headers returned:
    • LIMIT - The used limit parameter
    • OFFSET - The used offset parameter
    • TOTAL - The total number of conversations found (independent of limit/offset)
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID or AUTH_USERNAME
      • missing all of [group_id / conv_id / tag / owner] - at least one must be provided
      • Unrecognized group_id
      • offset < 1
    • 404 Not Found - Unrecognized AUTH_USERNAME
    • 500 Internal Error - a server-side error
    • 200 Success


• HEAD /f_convs/<conv_id>
  Returns a count of a specific conversation and all of its children.
  • Filters include the following query string parameters:
    • owner - find by the conversation creator - ?owner=<owner email>
    • group - ?group=<group_id>. Specify multiple groups with group[]=<group1_id>&group[]=<group2_id>
    • tag - ?tag=<tag>. Specify multiple tags with tag[]=<Tag1>&tag[]=<Tag2>
    • created_at - Use iso8601 formatted date time. Filters so only conversations created after specified time are returned.
    • limit - Limits number of conversations returned. Defaults to 10.
    • offset - Starts first conversation returned at the specified offset. Defaults to 1.
  • Headers returned:
    • LIMIT - The used limit parameter
    • OFFSET - The used offset parameter
    • TOTAL - The total number of conversations found (independent of limit/offset)
  • Responses:
    • 400 Bad Request -
      • missing BSGRA_GUID or AUTH_USERNAME
      • missing all of [group_id / conv_id / tag / owner] - at least one must be provided
      • Unrecognized group_id
      • offset < 1
    • 404 Not Found - unrecognized AUTH_USERNAME
    • 500 Internal Error - server-side error
    • 200 Success

© Copyright 2006-8 nGenera Corporation - All rights reserved. Version 2.6.1