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 GMTrss_search_json search_response_01
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
}
]
}
}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.
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.
| Header | Description |
|---|---|
| Content-Type | application/xml, text/xml, or application/json |
Response Body
| Name | Description |
|---|---|
| title | The title of the RSS channel; in this case, Search Results. |
| description | Description of the RSS channel, including the search criteria that were specified. |
| pubdate | The date of the search. |
| startIndex | The starting position for the search results page. This corresponds to the start value in the request parameters. |
| totalResults | The total number of results matching the request, even if a subset of total results is returned. |
| itemsPerPage | The 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:
|
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.
| Item | Value |
|---|---|
| 401 | Unauthorized. 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. |
| 500 | An error occurred processing the call. |
More information about Akana API Platform API error messages.