Please go to Organization Service for latest API.
What follows is a proposed API that will allow WikiForce to interact with a hub. It is broken down by resource in order to remain consistent with the RESTful design patterns used by the rest of the platform.
Visit the new Organization Service to see the API in action!
All calls require the following headers:
- BSGRA_GUID => the application ID associated with the client application. The application will be provisioned according to this ID, so separate Wikiforce instances will have separate IDs and separate provisions. This is the mechanism by which a wikiforce instance can establish affinity for a certain hub.
- AUTH_USERNAME => this is the hub username, which is actually an email address
Note that AUTH_USERNAME is just there for convenience during early development, and will be replaced with AUTH_ID soon.
Resource Type: F_CONV
- An F_CONV resource is a wrapper for a CONV resource, representing a wiki or a reply.
- Every resource has a unique ID.
Create or respond to an F_CONV
When creating a new conversation, tag the conversation once to place it in an F_INTERESTGROUP, and again to place it on the appropriate tab within the group. Send a parent f_conv id to reply to an existing f_conv.
POST host/f_convs
Body:
conv => <f_conv>
<type>Conv or Wiki</type>
<subject>max 255 chars</subject>
<body/>
<tag_list>group tag, opportunity (tab) tag</tag_list>
<parent>parent f_conv id</parent>
</f_conv>
Returns:
<f_conv>
<id/>
</f_conv>
HTTP Response Codes:
Success: 200
Bad Data: 400 (Unrecognized type or parent ID)
Authentication Failure: 401
Internal Error: 500
Modify an F_CONV
PUT host/f_convs/<f_conv id>
Body:
conv => <f_conv>
<subject>max 255 chars</subject>
<body/>
<tag_list>group tag, opportunity (tab) tag</tag_list>
</f_conv>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Conv Not Found: 404
Internal Error: 500
Get the F_CONVs within an F_INTERESTGROUP
This method will return only the ROOT f_convs.
GET host/f_convs?group=<f_interestgroup_id>
Returns:
<f_convs>
<f_conv>
<id/>
<type/>
<subject/>
<body/>
<tag_list/>
<parent/>
<created_at/>
<published_at/>
<updated_at/>
<name/>
<email/>
</f_conv>
<f_conv> ... </f_conv>
<f_conv> ... </f_conv>
</f_convs>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Get the F_CONVs within any of multiple F_INTERESTGROUPs
This method will return only the ROOT f_convs.
GET host/f_convs?group[]=<f_interestgroup_id>&group[]=<f_interestgroup2_id>
Returns:
<f_convs>
<f_conv>
<id/>
<type/>
<subject/>
<body/>
<tag_list/>
<parent/>
<created_at/>
<published_at/>
<updated_at/>
<name/>
<email/>
</f_conv>
<f_conv> ... </f_conv>
<f_conv> ... </f_conv>
</f_convs>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Get the F_CONVs with a specific tag
This method will return only the ROOT f_convs.
GET host/f_convs?tag=<tag>
Returns:
<f_convs>
<f_conv>
<id/>
<type/>
<subject/>
<body/>
<tag_list/>
<parent/>
<created_at/>
<published_at/>
<updated_at/>
<name/>
<email/>
</f_conv>
<f_conv> ... </f_conv>
<f_conv> ... </f_conv>
</f_convs>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Get the F_CONVs with any of several tags
This method will return only the ROOT f_convs.
GET host/f_convs?tag[]=<tag>&tag[]=<tag2>
Returns:
<f_convs>
<f_conv>
<id/>
<type/>
<subject/>
<body/>
<tag_list/>
<parent/>
<created_at/>
<published_at/>
<updated_at/>
<name/>
<email/>
</f_conv>
<f_conv> ... </f_conv>
<f_conv> ... </f_conv>
</f_convs>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Get a specific F_CONV with children
This method will return a list of f_convs, starting with the requested root and including the children of that root.
GET host/f_convs/<f_conv id>
Returns:
<f_convs>
<f_conv> ... </f_conv>
<f_conv> ... </f_conv>
</f_convs>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Conv Not Found: 404
Internal Error: 500
Delete an F_CONV
DELETE host/f_convs/<f_conv id>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Wiki Not Found: 404
Internal Error: 500
Resource Type: F_INTERESTGROUP
- An F_INTERESTGROUP resource is currently a proxy for an EXTERNAL_GROUP resource. As the Organization/Relationship service takes off, F_INTERESTGROUP will probably proxy to ORGANIZATION. Backwards compatibility will be maintained.
Create an F_INTERESTGROUP
Note: The created_by attribute will be ignored until SSO with SFDC is fully operation. Until that time, the hub proxy will operate under the aegis of an 'SFDC_User'.
POST host/f_interestgroups
Body:
- group => <f_interestgroup>
<name/>
<created_by>username</created_by>
<section_tags>Section tags</section_tags>
</f_interestgroup>
Returns:
<f_interestgroup>
<id/>
</f_interestgroup>
HTTP Response Codes:
Success: 200 (The group was created)
Bad Request: 400 (the request was malformed - possibly a missing name or a missing application ID)
Authentication Failure: 401 (not currently in use)
Name already exists: 409
Internal Error: 500
Update an F_INTERESTGROUP
PUT host/f_interestgroups/<group id>
Body:
- group => <f_interestgroup>
<name/>
<created_by>username</created_by>
<section_tags>Section Tags</section_tags>
<created_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</created_at>
</f_interestgroup>
Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Delete an F_INTERESTGROUP
DELETE host/f_interestgroup/<group id>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Get a list of F_INTERESTGROUPS
GET host/f_interestgroups
Returns:
<f_interestgroups>
<f_interestgroup>
<id/>
<name/>
<created_by>user ID</username>
<owner_email>username</owner_email>
<section_tags>Section Tags</section_tags>
<created_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</created_at>
<updated_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</updated_at>
<tag_cloud><tag><name/><value/></tag></tag_cloud>
<membership>
<member>
<guid>45038c42-a2d6-11dc-88e1-0019d1039198</guid>
<email>tech-support@kalivo.com</email>
<name>nGenera Tech Support</name>
</member>
<member>
<guid>2ddd3a70-b0cf-11dc-ba83-0030488b5524</guid>
<email>anonymous@kalbsgivo.com</email>
<name/>
</member>
</membership>
</f_interestgroup>
<f_interestgroup>
<id/>
<name/>
<created_by>username</created_by>
<owner_email />
<section_tags />
<created_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</created_at>
<updated_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</updated_at>
<tag_cloud><tag><name/><value/></tag></tag_cloud>
<membership>
<member>
<guid>9dd259dc-b651-11dc-9c6d-0030488b5524</guid>
<email>xgreggrosh@mac.com</email>
<name>Greg Grosh</name>
</member>
<member>
<guid>9dd3f742-b651-11dc-9c6d-0030488b5524</guid>
<email>xsscrupski@bsgalliance.com</email>
<name>Susan Scrupski</name>
</member>
</membership>
</f_interestgroup>
</f_interestgroups>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Internal Error: 500
Get a single F_INTERESTGROUP
GET host/f_interestgroups/<group id>
Returns:
<f_interestgroup>
<id/>
<name/>
<created_by>username</created_by>
<owner_email>user email</owner_email>
<section_tags>Section Tag</section_tags>
<created_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</created_at>
<updated_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</updated_at>
<membership>
<member>member id</member>
<member>member id</member>
<member>member id</member>
</membership>
<tag_cloud><tag><name/><value/></tag></tag_cloud>
<f_interestgroup/>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Internal Error: 500
Add a member to an F_INTEREST_GROUP
POST host/f_memberships
Body:
membership =>
<f_membership>
<group>group id</group>
<entity>user name or user email</entity>
</f_membership>
Response:
membership =>
<f_membership>
<group>group id</group>
<entity>entity id</entity_id>
</f_membership>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group or Entity Not Found: 404
Internal Error: 500
Delete a member from an F_INTEREST_GROUP
DELETE host/f_memberships/<group_id>/<user_id>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group or Entity Not Found: 404
Internal Error: 500
What follows is a proposed API that will allow WikiForce to interact with a hub. It is broken down by resource in order to remain consistent with the RESTful design patterns used by the rest of the platform.
Visit the new Organization Service to see the API in action!
All calls require the following headers:
- BSGRA_GUID => the application ID associated with the client application. The application will be provisioned according to this ID, so separate Wikiforce instances will have separate IDs and separate provisions. This is the mechanism by which a wikiforce instance can establish affinity for a certain hub.
- AUTH_USERNAME => this is the hub username, which is actually an email address
Note that AUTH_USERNAME is just there for convenience during early development, and will be replaced with AUTH_ID soon.
Resource Type: F_CONV
- An F_CONV resource is a wrapper for a CONV resource, representing a wiki or a reply.
- Every resource has a unique ID.
Create or respond to an F_CONV
When creating a new conversation, tag the conversation once to place it in an F_INTERESTGROUP, and again to place it on the appropriate tab within the group. Send a parent f_conv id to reply to an existing f_conv.
POST host/f_convs
Body:
conv => <f_conv>
<type>Conv or Wiki</type>
<subject>max 255 chars</subject>
<body/>
<tag_list>group tag, opportunity (tab) tag</tag_list>
<parent>parent f_conv id</parent>
</f_conv>
Returns:
<f_conv>
<id/>
</f_conv>
HTTP Response Codes:
Success: 200
Bad Data: 400 (Unrecognized type or parent ID)
Authentication Failure: 401
Internal Error: 500
Modify an F_CONV
PUT host/f_convs/<f_conv id>
Body:
conv => <f_conv>
<subject>max 255 chars</subject>
<body/>
<tag_list>group tag, opportunity (tab) tag</tag_list>
</f_conv>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Conv Not Found: 404
Internal Error: 500
Get the F_CONVs within an F_INTERESTGROUP
This method will return only the ROOT f_convs.
GET host/f_convs?group=<f_interestgroup_id>
Returns:
<f_convs>
<f_conv>
<id/>
<type/>
<subject/>
<body/>
<tag_list/>
<parent/>
<created_at/>
<published_at/>
<updated_at/>
<name/>
<email/>
</f_conv>
<f_conv> ... </f_conv>
<f_conv> ... </f_conv>
</f_convs>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Get the F_CONVs within any of multiple F_INTERESTGROUPs
This method will return only the ROOT f_convs.
GET host/f_convs?group[]=<f_interestgroup_id>&group[]=<f_interestgroup2_id>
Returns:
<f_convs>
<f_conv>
<id/>
<type/>
<subject/>
<body/>
<tag_list/>
<parent/>
<created_at/>
<published_at/>
<updated_at/>
<name/>
<email/>
</f_conv>
<f_conv> ... </f_conv>
<f_conv> ... </f_conv>
</f_convs>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Get the F_CONVs with a specific tag
This method will return only the ROOT f_convs.
GET host/f_convs?tag=<tag>
Returns:
<f_convs>
<f_conv>
<id/>
<type/>
<subject/>
<body/>
<tag_list/>
<parent/>
<created_at/>
<published_at/>
<updated_at/>
<name/>
<email/>
</f_conv>
<f_conv> ... </f_conv>
<f_conv> ... </f_conv>
</f_convs>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Get the F_CONVs with any of several tags
This method will return only the ROOT f_convs.
GET host/f_convs?tag[]=<tag>&tag[]=<tag2>
Returns:
<f_convs>
<f_conv>
<id/>
<type/>
<subject/>
<body/>
<tag_list/>
<parent/>
<created_at/>
<published_at/>
<updated_at/>
<name/>
<email/>
</f_conv>
<f_conv> ... </f_conv>
<f_conv> ... </f_conv>
</f_convs>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Get a specific F_CONV with children
This method will return a list of f_convs, starting with the requested root and including the children of that root.
GET host/f_convs/<f_conv id>
Returns:
<f_convs>
<f_conv> ... </f_conv>
<f_conv> ... </f_conv>
</f_convs>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Conv Not Found: 404
Internal Error: 500
Delete an F_CONV
DELETE host/f_convs/<f_conv id>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Wiki Not Found: 404
Internal Error: 500
Resource Type: F_INTERESTGROUP
- An F_INTERESTGROUP resource is currently a proxy for an EXTERNAL_GROUP resource. As the Organization/Relationship service takes off, F_INTERESTGROUP will probably proxy to ORGANIZATION. Backwards compatibility will be maintained.
Create an F_INTERESTGROUP
Note: The created_by attribute will be ignored until SSO with SFDC is fully operation. Until that time, the hub proxy will operate under the aegis of an 'SFDC_User'.
POST host/f_interestgroups
Body:
- group => <f_interestgroup>
<name/>
<created_by>username</created_by>
<section_tags>Section tags</section_tags>
</f_interestgroup>
Returns:
<f_interestgroup>
<id/>
</f_interestgroup>
HTTP Response Codes:
Success: 200 (The group was created)
Bad Request: 400 (the request was malformed - possibly a missing name or a missing application ID)
Authentication Failure: 401 (not currently in use)
Name already exists: 409
Internal Error: 500
Update an F_INTERESTGROUP
PUT host/f_interestgroups/<group id>
Body:
- group => <f_interestgroup>
<name/>
<created_by>username</created_by>
<section_tags>Section Tags</section_tags>
<created_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</created_at>
</f_interestgroup>
Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Delete an F_INTERESTGROUP
DELETE host/f_interestgroup/<group id>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group Not Found: 404
Internal Error: 500
Get a list of F_INTERESTGROUPS
GET host/f_interestgroups
Returns:
<f_interestgroups>
<f_interestgroup>
<id/>
<name/>
<created_by>user ID</username>
<owner_email>username</owner_email>
<section_tags>Section Tags</section_tags>
<created_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</created_at>
<updated_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</updated_at>
<tag_cloud><tag><name/><value/></tag></tag_cloud>
<membership>
<member>
<guid>45038c42-a2d6-11dc-88e1-0019d1039198</guid>
<email>tech-support@kalivo.com</email>
<name>nGenera Tech Support</name>
</member>
<member>
<guid>2ddd3a70-b0cf-11dc-ba83-0030488b5524</guid>
<email>anonymous@kalbsgivo.com</email>
<name/>
</member>
</membership>
</f_interestgroup>
<f_interestgroup>
<id/>
<name/>
<created_by>username</created_by>
<owner_email />
<section_tags />
<created_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</created_at>
<updated_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</updated_at>
<tag_cloud><tag><name/><value/></tag></tag_cloud>
<membership>
<member>
<guid>9dd259dc-b651-11dc-9c6d-0030488b5524</guid>
<email>xgreggrosh@mac.com</email>
<name>Greg Grosh</name>
</member>
<member>
<guid>9dd3f742-b651-11dc-9c6d-0030488b5524</guid>
<email>xsscrupski@bsgalliance.com</email>
<name>Susan Scrupski</name>
</member>
</membership>
</f_interestgroup>
</f_interestgroups>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Internal Error: 500
Get a single F_INTERESTGROUP
GET host/f_interestgroups/<group id>
Returns:
<f_interestgroup>
<id/>
<name/>
<created_by>username</created_by>
<owner_email>user email</owner_email>
<section_tags>Section Tag</section_tags>
<created_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</created_at>
<updated_at>EEE, dd MMM YYYY HH:mm:ss -ZZZZ</updated_at>
<membership>
<member>member id</member>
<member>member id</member>
<member>member id</member>
</membership>
<tag_cloud><tag><name/><value/></tag></tag_cloud>
<f_interestgroup/>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Internal Error: 500
Add a member to an F_INTEREST_GROUP
POST host/f_memberships
Body:
membership =>
<f_membership>
<group>group id</group>
<entity>user name or user email</entity>
</f_membership>
Response:
membership =>
<f_membership>
<group>group id</group>
<entity>entity id</entity_id>
</f_membership>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group or Entity Not Found: 404
Internal Error: 500
Delete a member from an F_INTEREST_GROUP
DELETE host/f_memberships/<group_id>/<user_id>
HTTP Response Codes:
Success: 200
Authentication Failure: 401
Group or Entity Not Found: 404
Internal Error: 500