GET /api/search

Returns search results for a specified string.

Search results vary according to the user's status. If the user is not logged in, the search results include information about public APIs and public apps. However, if the user logs in, and is a member of one or more API Scope Groups or app teams, search results will include information about the apps and APIs that the user is authorized to access.

For more examples of using the Search feature, see Using Search on the Platform.

Authorization Roles/Permissions: Login is not required for search. However, if the user doesn't have permission to view certain resources, those resources are excluded from search results.

This topic includes the following sections:

HTTP Method

GET

URL

https://{hostname}/api/search?{q}={SearchExpression}&sort={sort}&sortBy={sortBy}&start={start}&count={count}

Sample Request

Several examples of using this API are shown below.

Note: For additional examples, see Using Search on the Platform (Sample Search URLs section).

Sample request URL #1

The example below shows a search for groups, requesting the first two responses. This query returns the first two groups that the user has visibility of. See Sample response body #1.

https://{hostname}/api/search?count=2&start=0&q=type:group

Sample request URL #2

The example below shows a request for information based on a specific unique ID. This query returns the response shown in Sample response body #2: Postman.

https://{hostname}/api/search?q=d37990e2-800a-4963-b3b9-908b6a87dbcc.acmepaymentscorp

Sample request URL #3

the example below shows a search for model objects.This query returns the response shown in Sample response body #3.

https://{hostname}/api/search?q=type:model

Sample request URL #4

The example below shows a search for oauth.

https://{hostname}/api/search?count=20&start=0&q=type:*%20AND%20oauth

Sample request URL #5

The example below shows a search for the list of all users.

https://{hostname}/api/search?sort=asc&sortBy=com.soa.sort.order.title_sort&Federation=false&count=20&start=0&q=type:user

Sample request headers

accept: application/json

Sample request body

Not applicable.

Request Headers

For general information on request header values, refer to HTTP Request Headers.

Header Description
Accept application/xml, text/xml, or application/json

Request Parameters

Parameter Parm Type Data Type Required Description
q Query string Required

The search term or phrase; for example, Payments. Use encoding for spaces between words; for example, ACME%20Payments for ACME Payments. You can use q=type: to specify a type of resource you want to search. For valid values, see Search "Type" Values.

For more information about search expressions, see Using Search on the Platform.

sort Query string Optional The sort order for the search results; for example, asc for ascending order. For valid values, see Sort Order Values.
sortBy Query string Optional An optional parameter allowing users to sort results by a specific value; for example, com.soa.sort.order.updated sorts with the most updated entries first. For valid values, see Sort By Values. If not specified, items are returned in the sort order of DescendingDate, which means that the most recent items are first.
start Query integer Optional The starting position for the search results page. If not specified, defaults to 0.
count Query integer Optional The number of search results to be displayed on the search results page. If not specified, defaults to 20.
FollowedOnly Query boolean Optional Limits the search to only resources followed by the current user. Defaults to false.

UpdatedDateFrom

Version: 2019.1.2

Query string Optional

Allows you to retrieve objects added or updated after a certain date/time stamp. For example, you could use this to retrieve apps and app versions that were updated since the specified date/time. The example below retrieves up to 10,000 app versions that were updated since the specified date:

/api/search?q=(type:app-version)&UpdatedDateFrom=2019-09-09T00:00:00&count=10000

UpdatedDateTo

Version: 2019.1.2

Query string Optional

In combination with UpdatedDateFrom, allows you to retrieve objects, such as apps and app versions, that were updated in a specified date/time range. The example below retrieves all apps that were updated in the specified 1-hour time period:

/api/search?q=(type:app)&UpdatedDateFrom=2019-10-11T22:00:00&UpdatedDateTo=2019-10-11T23:00:00

Response

If successful, this operation returns HTTP status code 200, with the requested search results. The response is formatted as an RSS feed.

Sample Response

The examples below show successful use of this operation.

Sample response headers #1

Status Code: 200 OK
Content-Type: application/json
Date: Thu, 21 May 2020 20:26:11 GMT
rss_search_json search_response_01

Sample response body #1

The sample response below shows results for the GET /api/search method when searching for groups and requesting the first two (sample request URL #1).

{
  "channel": {
    "title": "Search Results",
    "description": "Search results for [type:group]",
    "pubDate": "Thu May 21 20:26:11 UTC 2020",
    "startIndex": 0,
    "totalResults": 4,
    "itemsPerPage": 2,
    "elapsedTime": 28,
    "item": [
      {
        "title": "Private Group 3",
        "description": "Private Group 3",
        "category": [
          {
            "value": "group",
            "domain": "uddi:soa.com:resourcetype"
          },
          {
            "value": "com.soa.imageprovider.type.default",
            "domain": "uddi:soa.com:avatar-provider"
          },
          {
            "value": "Limited",
            "domain": "uddi:soa.com:visibility"
          }
        ],
        "guid": {
          "value": "1c95952f-a53b-47ad-8a2f-f02d92ed6d26.acmepaymentscorp"
        },
        "Rating": 0.0,
        "Image": {
          "Url": "https://acmepaymentscorp.apiportal.akana.com:443/api/groups/avatar/_V8x3edl7eb0sGwDLpdZR1IQ"
        },
        "Followers": 0
      },
      {
        "title": "Private Group 1",
        "description": "Private Group 1",
        "category": [
          {
            "value": "group",
            "domain": "uddi:soa.com:resourcetype"
          },
          {
            "value": "com.soa.imageprovider.type.default",
            "domain": "uddi:soa.com:avatar-provider"
          },
          {
            "value": "Limited",
            "domain": "uddi:soa.com:visibility"
          }
        ],
        "guid": {
          "value": "e2eb5c36-ae70-4dc9-85ab-e039fd6e125d.acmepaymentscorp"
        },
        "Rating": 0.0,
        "Image": {
          "Url": "https://acmepaymentscorp.apiportal.akana.com:443/api/groups/avatar/_VOF-tsBCHDT998KwVfpYDxWQ"
        },
        "Followers": 0
      }
    ]
  }
}

Sample response #2: Postman

The example below illustrates using Postman to return search information. This response corresponds to sample request URL #2, also example #8 in the Sample Search URLs section of Using Search on the Platform. It returns information based on a specific unique ID.

Search example using Postman

Sample response #3: Models List

The example below illustrates the list of models returned by the Community Manager developer portal user interface on the {Business} > Models page. This response corresponds to sample request URL #3.

{
  "channel": {
    "title": "Search Results",
    "description": "Search results for [type:model]",
    "pubDate": "Thu May 21 21:08:03 UTC 2020",
    "startIndex": 0,
    "totalResults": 2,
    "itemsPerPage": 2,
    "elapsedTime": 0,
    "item": [
      {
        "title": "Check Purchase",
        "description": "",
        "category": [
          {
            "value": "model",
            "domain": "uddi:soa.com:resourcetype"
          },
          {
            "value": "com.akana.model.state.draft",
            "domain": "uddi:soa.com:state"
          },
          {
            "value": "global",
            "domain": "uddi:soa.com:modelcategory"
          },
          {
            "value": "Public",
            "domain": "uddi:soa.com:visibility"
          }
        ],
        "guid": {
          "value": "f20eeab0-a489-4be1-9d84-e25140d093eb.acmepaymentscorp"
        },
        "EntityReferences": {
          "EntityReference": [
            {
              "Guid": "8b76c88a-5ef0-4950-8fb7-6c20bd8852bc.acmepaymentscorp",
              "Category": [
                {
                  "value": "modelversion",
                  "domain": "uddi:soa.com:resourcetype"
                }
              ]
            },
            {
              "Title": "acmepaymentscorp",
              "Guid": "tenantbusiness.acmepaymentscorp",
              "Category": [
                {
                  "value": "business",
                  "domain": "uddi:soa.com:resourcetype"
                }
              ]
            }
          ]
        }
      },
      {
        "title": "Cash Purchase",
        "description": "",
        "category": [
          {
            "value": "model",
            "domain": "uddi:soa.com:resourcetype"
          },
          {
            "value": "com.akana.model.state.draft",
            "domain": "uddi:soa.com:state"
          },
          {
            "value": "global",
            "domain": "uddi:soa.com:modelcategory"
          },
          {
            "value": "Public",
            "domain": "uddi:soa.com:visibility"
          }
        ],
        "guid": {
          "value": "4f1d8eba-dd0a-4bbc-9b71-4bf0207dde11.acmepaymentscorp"
        },
        "EntityReferences": {
          "EntityReference": [
            {
              "Guid": "a1604329-afec-4d8e-b41f-2fa7a63cc99e.acmepaymentscorp",
              "Category": [
                {
                  "value": "modelversion",
                  "domain": "uddi:soa.com:resourcetype"
                }
              ]
            },
            {
              "Title": "acmepaymentscorp",
              "Guid": "tenantbusiness.acmepaymentscorp",
              "Category": [
                {
                  "value": "business",
                  "domain": "uddi:soa.com:resourcetype"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Response Headers

For general information on response header values, refer to HTTP Response Headers.

HeaderDescription
Content-Typeapplication/xml, text/xml, or application/json

Response Body

NameDescription
titleThe title of the RSS channel; in this case, Search Results.
descriptionDescription of the RSS channel, including the search criteria that were specified.
pubdateThe date of the search.
startIndexThe starting position for the search results page. This corresponds to the start value in the request parameters.
totalResultsThe total number of results matching the request, even if a subset of total results is returned.
itemsPerPageThe number of search results to be displayed on the search results page. This corresponds to the count value in the request parameters.
Item

An array of individual search results. For each item:

  • Title
  • Description
  • Category[ ]—One or more categories for the search results. Each category includes value and domain, name/value pairs.
  • GUID: the unique ID for the item.
  • EntityReferences—includes one or more nested EntityReference objects. For each: Title, GUID, Category. Each category includes value and domain, name/value pairs.
  • Connections
  • Ratings

Error Codes/Messages

If the call is unsuccessful an error code/message is returned. One or more examples of possible errors for this operation are shown below.

ItemValue
401Unauthorized. For example, you would get this response if you didn't include the custom X-Csrf-Token_{fedmemberID} header in the request, when it was required by the platform settings; or if you included an invalid or expired value for this header. You would also get this response for any operation that requires login (almost all) if the login cookie was missing.
500An error occurred processing the call.

More information about Akana API Platform API error messages.