Community articleSearch REST API specification
Added by IBM contributorIBM | Edited by IBM contributorAndreas Prokoph on October 6, 2015
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

This document describes the API call format for searching IBM WebSphere Portal content
Tags: 8.0, API, SPI

This document describes the API call for searching IBM WebSphere Portal to find content that, for example, contains a specific text string in its title or content, or is tagged with a specific tag.

Request Format


Context Paths


There are a number of different context paths available for this API in order to allow for different authentication mechanisms:-
 

Context Path Authentication
//contenthandler/searchfeed/search  
None
//mycontenthandler/searchfeed/search  
Basic

 

Parameters


The order of the parameters in the requests do not matter. The parameter names are case-sensitive; they must be entered in the format documented. Any unknown or unsupported parameters submitted as part of a request will be ignored.

The request should be a standard HTTP GET or POST command. When the request is GET the URL is formed by combining the search server's host name, port and path; as well as a collection of name-value pairs (input parameters) separated by & characters. Any parameter value must be URL-escaped if in GET request. When the request is POST the search server's host name, port and path, as well as a collection of name-value pairs (input parameters) are past on the request as parameters.

 

 

Name
Description
Comments
  • locale
  • Locale of request client
    • any message returned will be in the client locale
    • available scopes and collections titles and description will be in the client locale
    • sorting method might be effected by the locale
    • Any additional information in the search results that are locale aware, like description
  • Specifies the language to use to parse the search request. See ISO-639 and ISO-3166 for valid values, e.g. "en_US". This parameter is optional. When specified, the appropriate dictionary for the specified language is used. Note: The dictionary for the language specified must be enabled for this parameter to work.
  • query

 

 Text to search for. Returns a list of results with the specified text in the title, description, or content. Encode the strings. By default, spaces are treated as an OR operator. The following operators are supported:

AND or &&: Searches for items that contain both words. For example: query=red%20AND%20test returns items that contain both the word red and the word test. AND is the default operator.

NOT or !: Excludes the word that follows the operator from the search. For example: query=test%20NOT%20red returns items that contain the word test, but not the word red.

OR: Searches for items that contain either of the words. For example: query=test%20OR%20red
To search for a phrase, enclose the phrase in quotation marks (" ").

+: The plus sign indicates that the word must be present in the result. For example: query=+test%20red returns only items that contain the word test and many that also contain red, but none that contain only the word red.

?: Use a question mark to match individual characters. For example: query=te%3Ft returns items that contain the words test, text, tent, and others that begin with te.

-: The dash prohibits the return of a given word. This operator is similar to NOT. For example: query=test%20-red returns items that contains the word test, but not the word red.

Note: Wildcard searches are permitted, but wildcard only searches (*) are not.
For more details about supported operators, see Advanced search options in the Using section of the product documentation

  • queryLang
  • Language of the query string
  • Specifies the language to use to parse the query parameter. See ISO-639 and ISO-3166 for valid values, e.g. "en_US". This parameter is optional. When specified, the appropriate dictionary for the specified language is used. Note: The dictionary for the language specified must be enabled for this parameter to work.
  • start
  • Offset to first result to return in results
  • Defines an offset from the first result in the set. This parameter is ignored if a page parameter is provided. This starts from 0. The default is 0. If specified value is negative, the value will be defaulted to 0; if the specified value is greater than the number of results, no results will be returned.
  • page
  • Page number
  • Specifies the page to be returned. The default value is 1, which returns the first page.
  • pageSize
  • Number of results desired for a single request
  • Specifies the number of entries to return per page. The minimum value is zero (negative values default to zero). The default value is 10. The maximum value you can specify is 150.
  • scope
  • Identifier of which scope to search; the list of valid scopes is available from the
Scopes API
  • Default is to search over all scopes.
  • sortKey
  • The key which controls the sorting order of the search results
  • The following values are supported: "date" and "relevance".
  • sortOrder
  • Determines the order by which the results are sorted: ascending or descending
  • The only valid values are "asc" or "desc"
  • constraint
  • Allows constraining the search results according to the provided criteria.
Refer to Constraints API for more information.
  • facet
  • Specify which facets will be returned for the query, in addition to search results.
Refer to Facets API for more information.
index specify which index (collection) to use for the search Refer to Indices API for more information

Examples

/searchfeed/search?queryLang=en&locale=en&resultLang=en&query=development&scope=1345374377545&start=0&results=10

Search query with query text = "development".

Response Format


The response is Atom compliant. The table below describes the significance of the elements returned in the response:

 

Section
Remarks
  • /feed
  • The container element for metadata and data that is associated with the search results feed.
  • /feed/title
  • Descriptive title of the feed.
  • /feed/link[@href]
  • Reference from the feed to a Web resource.
  • /feed/link[@rel= "next"|"previous"|"first"|"last"]
RFC5005 Section-3
  • "first", "last", "next" and "previous" links are included, as appropriate, for supporting .
  • /feed/author/name
  • Description of the feed generator.
  • /feed/id
  • Permanent, universally unique identifier for the feed.
  • /feed/updated
  • Date/time the query was issued. The value will conform to the date-time production in RFC3339.
  • /feed/openSearch:totalResults
  • Total number of results for submitted query.
  • /feed/openSearch:Query
  • Contains information about the query that was submitted by the user.
  • /feed/openSearch:Query[@role]
  • The role attribute value will be "request".
  • /feed/openSearch:Query[@searchTerms]
  • Represents the user submitted query terms.
  • /feed/openSearch:startIndex
  • Initial result number for the search results returned in this feed.
  • /feed/openSearch:itemsPerPage
  • Number of search results returned in this feed.
  • /feed/entry
  • Encompasses the information for a single search result.
  • /feed/entry/category
  • /feed/entry/category@term
/feed/entry/category@scheme An IRI that identifies a categorization scheme. Refer to Categories in Search API responsesCreate New Article for more information.
  • /feed/entry/title
Text construct that conveys a human-readable title for an entry.
/feed/entry/title[@type] Indicates whether the text construct is "text", "html" or "xhtml". Text construct is "text" if not otherwise specified.
  • /feed/entry/link
  • Defines a reference to the search result resource.
  • /feed/entry/link[@rel]
  • Indicates the link relation type. If not present, the link relation type is "alternate".
  • /feed/entry/link[@href]
  • URI link to document
  • /feed/entry/link[@type]
  • Content type of the URI document link is an advisory media type.
  • /feed/entry/relevance:score
Indicates a relative assessment of relevance for a particular search result with respect to the search query.
  • /feed/entry/updated
  • Last modified date for the document. The value will conform to the date-time production in RFC3339.
  • /feed/entry/id
  • Unique identifier of the document.
  • /feed/entry/summary
Text construct that conveys a short summary, abstract, or excerpt of an entry.
/feed/entry/summary[@type] Indicates whether the text construct is "text", "html" or "xhtml". Text construct is "text" if not otherwise specified.
  • /feed/entry/author
A person construct that indicates the author of the entry or feed.
  • /feed/entry/author/name
  • Human-readable name for the person.
  • /feed/entry/author/uri
  • Identifier associated with the person.
  • /feed/entry/author/email
  • The person email address. This may not be returned as part of the feed depending on the IBM Connections configuration settings.
  • /feed/entry/wplc:field
  • This element is used to represent the name and value of a field of a document. The id attribute represents the name of the field. The body of the element represents the value of the field. Additional fields will be included in the search result response if specified through the includeField parameter.
  • /feed/ibmsc:facets
  • Refer to FacetsCreate New Article for more information.
   

Example


To search for all content across IBM WebSphere Portal that contains the text Development, send the following HTTP request:


> GET /searchfeed/search?query=development&scope=com.ibm.lotus.search.ALL_SOURCES HTTP/1.1



The following content is returned by the server:


<?xml version="1.0" encoding="UTF-8"?>


   <atom:feed xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"

      xmlns:xhtml="http://www.w3.org/1999/xhtml"

      xmlns:wplc="http://www.ibm.com/wplc/atom/1.0"

      xmlns:atom="http://www.w3.org/2005/Atom">

      <atom:title>Search results for query "development" on scope "com.ibm.lotus.search.ALL_SOURCES"</atom:title>

      <atom:link href="searchfeed:search" rel="self" type="application/atom+xml"/>

      <atom:author>

          <atom:name>Enterprise Search API Web Service.</atom:name>

      </atom:author>

      <atom:id>searchfeed:search</atom:id>

      <atom:category term="com.ibm.lotus.search.ALL_SOURCES" label="com.ibm.lotus.search.ALL_SOURCES"/>

      <atom:updated>2013-01-14T08:35:27.482Z</atom:updated>

      <opensearch:totalResults exact="true">412</opensearch:totalResults>

      <opensearch:Query role="request" searchTerms="development"/>

      <opensearch:startIndex>0</opensearch:startIndex>

      <opensearch:itemsPerPage>10</opensearch:itemsPerPage>



      <atom:entry>

         <atom:id>ResourceinjectionusingRationalApplicationDeveloperv7.5</atom:id>

         <atom:title type="text/html">Resource injection using Rational Application Developer v7.5</atom:title>

         <atom:author>

            <atom:uri>Dan_Haim</atom:uri>

            <atom:name>Dan Haim</atom:name>

         </atom:author>

         <atom:author>

            <atom:uri>James_Chung</atom:uri>

            <atom:name>James Chung</atom:name>

         </atom:author>

         <atom:link href="http://www.ibm.com/developerworks/rational/library/10/resourceinjectionwithrad7-5/index.html"/>

         <atom:category term="ContentSourceType/default" scheme="com.ibm.wplc.taxonomy://feature_taxonomy" label="Document"/>

         <opensearch:relevance>100.0</opensearch:relevance>

         <atom:updated>2010-06-07T06:49:09.000Z</atom:updated>

         <atom:summary type="html"><![CDATA[<Strong>Summary:</Strong> Java&#8482; platf....]]></atom:summary>

         <atom:link href="/wps/images/icons/Document.gif" rel="icon"/>

         <wplc:field id="name">95c189804d4268bf8d49ede9170f1e3d</wplc:field>

         <wplc:field id="contentSourceType">Seedlist</wplc:field>

         <wplc:field id="defaultcontext">/poc</wplc:field>

         <wplc:field id="effectivedate">1236246335000</wplc:field>

         <wplc:field id="modifier">Replicator</wplc:field>

         <wplc:field id="securecontext">/mypoc</wplc:field>

         <wplc:field id="search_controllable_uuid">2c1e7b59-b465-49da-bc99-5aee3c00932b</wplc:field>

         <wplc:field id="locale">en</wplc:field>

         <wplc:field id="RatingAverage">4</wplc:field>

         <wplc:field id="author_info">Dan_Haim<![CDATA[<Dan Haim<]]></wplc:field>

         <wplc:field id="author_info">James_Chung<![CDATA[<James Chung<]]></wplc:field>

         <wplc:field id="acls">public</wplc:field>

         <wplc:field id="authoringtemplate">Blog Home</wplc:field>

         <wplc:field id="popularity">7811</wplc:field>

         <wplc:field id="security_ids">Z6QReDeIPO2JIT62BDIJM8CKHDAJMG6P1P2MM8C3BEIJMK61BPAMPCCG1CIJP8623</wplc:field>

         <wplc:field id="difficulty">Advanced</wplc:field>

         <wplc:field id="contentPath">/Blog Solo Template v70/Blog/Home/95c189804d4268bf8d49ede9170f1e3d</wplc:field>

         <wplc:field id="category">Rational</wplc:field>

     </atom:entry>



      ...



</atom:feed>