Knowledge management: querying the document, entity and event databases

The most important API call performs searches, and ranks and aggregates documents and sub-objects like entities, associations, and metadata. The link below comprises a number of pages discussing the configuration and output.

• knowledge/document/query: performs a query and returns documents and metadata about the results

It is also possible to get individual documents (just metadata or metadata and content):

• knowledge/document/get: returns a single document given its "_id" field or its "sourceKey"/"url" pair.
• knowledge/document/file/get: returns a single document its "sourceKey" and relative path (fileshares only).

We call any element of the document data model that exists independently to the document a "feature" (including entities, geotags, entity associations). There are a number of methods to retrieve these features:

• knowledge/feature/entitySuggest: given free-form text, suggests matching entities.
• knowledge/feature/assocSuggest: given a semi-structured text input (under "subject"/"verb"/"object"), suggests matching entity associations.
• knowledge/feature/aliasSuggest: given an entity name, provides all known aliases of that entity.
• knowledge/feature/geoSuggest: give a lat/lng or a location name, suggests the opposite

Authentication methods

With a few minor exceptions, it is necessary to log-in before invoking any other methods. Some methods require system-wide admin privileges, indicated below with "(admin)". Other methods need to be approved by the community owner before they take effect, these are indicated below with "(community-approval)". Others can only be performed by the community owner, the content owner, or an admin, these are indicated below with "(owner/moderator/admin)". It is assumed that any call that takes a community ID requires membership of that community, apart from requesting to join public communities.

• auth/login: returns a cookie to make subsequent api calls after authenticating a user
• auth/login/admin (admin): returns an admin cookie to make subsequent admin api calls after authenticating an administrator
  
• auth/keepalive: updates a cookie to last for 30 more minutes
• auth/logout: removes a users cookie not allowing them to make api calls anymore
• auth/forgotpassword: starts process to receive password via email
• auth/deactivate (admin): turns off a users account so they can no longer log in

Logging out is optional - users can only be logged-in from one place and the older session is automatically terminated when the newer one begins.

If an API key is specifed (via REST or the GUI) then any API command can be authenticated with the URL parameter "infinite_api_key" instead of logging in. API keys can be used in cookies also, in the format "infinitecookie=api:API_KEY;".

Source management

These methods can be used to get information about the sources that IKANOW harvests to populate its database (see this overview). This might be needed in order to specify the inputs over which a query is run, or to check the harvest status of a source (either regularly or based on unexpected results).

• config/source/get: returns a source object given its "_id" field.
• config/source/good: returns a list of all active sources.
• config/source/user: returns a list of all sources owned or (optionally) visible to that user (or for admins - optionally all sources regardless of community).

These methods are more administrative:

• config/source/bad: lists unapproved sources (also sources that have been turned off by the IKANOW harvester due to issues in harvesting the source)
• config/source/pending: lists proposed sources that a community administrator has not yet approved.

The process of configuring source objects, which is basically simple but allows for sophisticated functionality in return for more complexity, is described here.

A key activity, either for Open Source Analysis or for mining an organizations internal data-stores, is creating source configuration objects. The link below comprises a number of pages describing the different possible configurations.

• config/source/save: (community-approval) for new sources, (owner/moderator/admin) for existing sources. Adds a new source to the harvest list
  
• config/source/add: (deprecated) (community-approval)
• config/source/test: tests a new source in the harvester to compare results and tweak source setup
• config/source/suspend: stops a source from harvesting or resumes a suspending source back again

After a source has been added, a request is sent to the community administrator, who has the option to accept or decline it. Only accepted sources are processed by the IKANOW harvester. "config/source/save" can be used by users with appropriate permissions to edit a source's status.

Admins and owners can remove documents from sources (or the sources themselves, which automatically removes the documents as well):

• config/source/delete: (owner/moderator/admin) removes a source from harvesting
  config/source/delete/docs: (owner/moderator/admin) removes specific harvested documents

Community methods

The Community API calls are used to manage communities (add, update, remove, and get). The APIs can be broken out into the following basic areas of functionality:

Basic community administration: APIs used to add a new community, remove an existing community, or update an existing community.

• social/community/add: adds a new community
• social/community/remove (owner/moderator/admin): removes a community
  social/community/update (owner/moderator/admin): changes information about a community

A user can retrieve their list of communities (together with other user metadata) with the "person/get" API call:

• social/person/get

A user can also retrieve a list of all other users they are in communities with:

• social/person/list

Community membership: APIs used to join (request membership in) a community, leave a community, invite a user to join a community, update a user's status within a community (active/pending), update user type (owner, moderator, user), and manage responses to invitation.

• social/community/member/join: (community-approval) attempts to join a community
• social/community/member/leave: removes yourself from a community
• social/community/member/invite: (owner/moderator/admin community-approval) invites a user to a community
• social/community/member/update/status: (owner/moderator/admin) updates a members status in a group (active,disabled,pending)
• social/community/member/update/type: (owner/moderator/admin) updates a members type in a group (owner,moderator,content_publisher,member)
• social/community/requestresponse: respond to community invite/join requests

Get: APIs used to retrieve data for one or more communities:

• social/community/get: retrieves a single community based on the community._id value
• social/community/getpublic: retrieves all publicly available communities
• social/community/getprivate: retrieves all private communities (including personal communities)
• social/community/getall: retrieves all communitities
• social/community/getsystem: retrieves the system community

(Note that wherever community approval or ownership is required, a system admin can also perform that task. In addition, community "moderators" can also add, remove, and update users.)

Share methods

The Share methods are used to allow the saving and sharing of queries, datasets, sources, documents, feeds, and other objects that can be encoded using standard JSON notation (or are arbitrary binary objects).

• social/share: all encompassing method to handle all the below methods in one nice package
• social/share/add/json: saves a json object to the share database
• social/share/update/json: (owner/moderator/admin): replaces a current json object with a new one in the share database
• social/share/remove: (owner/moderator/admin): deletes an object from the share database
• social/share/add/community: allows a community to access a share
• social/share/remove/community: disallows a community to access a share
• social/share/endorse: (moderator/admin): adds or removes an endorsed tag for a share within a community
• social/share/get: returns a share by _id
• social/share/search: searches shares for ones you have access to
• social/share/add/binary: adds a binary file to the share db
• social/share/update/binary: (owner/moderator/admin): replaces a current binary object with a new one in the share database
• social/share/add/ref: creates a shared "pointer" to an existing IKANOW artifact to the share database
• social/share/update/ref: (owner/moderator/admin): replaces a shared "pointer" to an existing IKANOW artifact with a new one in the share database

People

The People methods are admin functions used by the 3rd party user management systems (eg Wordpress web-site for the IKANOW SaaS version) to register and update users.  These calls must come from an authenticated IKANOW server or admins and will not work for other users.

• social/person/register:  (admin): registers a new user in the system
• social/person/update: (admin): updates a user in the system
• social/person/delete: (admin): removes a user from the system
• social/person/update/password: updates a users password
• social/person/update/email: updates a users email address(es)

Custom

These custom methods are related to running and viewing custom jobs.

• custom/mapreduce/schedulejob: schedules a hadoop map reduce job to be ran in the future, possibly on a regular interval
• custom/mapreduce/updatejob: updates a scheduled hadoop job, can be used to rerun a job
• custom/mapreduce/removejob: deletes a job and its data
• custom/mapreduce/getresults: returns the results from a map reduce job
• custom/mapreduce/getjobs: returns a list of jobs the current user has access to
• custom/savedquery/schedulejob: schedules a query job to be ran in the future, possibly on a regular interval
• custom/savedquery/updatejob: updates a scheduled query job, can be used to rerun a job

GUI integration

The uisetup methods are GUI specific methods for searching, storing, and getting modules (widgets).  Most API users will not need to use these methods

• social/gui/uisetup/get: returns a user's last saved uisetup including open widgets, last query, and advanced settings
• social/gui/uisetup/update: saves a users's uisetup so /uisetup/get will return it next time
• social/gui/modules/get: returns all widgets available to a user (for widget browser)
• social/gui/modules/install: Uploads or updates the metadata describing a widget (that allows it to be accessed from the widget browser)
• social/gui/modules/delete: Deletes all metadata describing a widget (ie the widget can no longer be accessed from the widget browser)
• social/gui/modules/user/get: returns a users last saved list of widgets (for widget browser)
• social/gui/modules/user/set: saves a users last set of widgets (for widget browser)
• social/gui/modules/search: searches all available widgets on title, author and description fields of widget