Difference between revisions of "stoney core: Search Resource - REST API"
From stoney cloud
| [unchecked revision] | [checked revision] |
(→Global Search Response Message Body) |
(→Overview) |
||
| (26 intermediate revisions by 2 users not shown) | |||
| Line 14: | Line 14: | ||
** Default: 5 | ** Default: 5 | ||
** Maximum: 15 (can be raised by '''entries''' get parameter) | ** Maximum: 15 (can be raised by '''entries''' get parameter) | ||
| − | |||
= stoney core: search resource methods = | = stoney core: search resource methods = | ||
| Line 26: | Line 25: | ||
== Global Search (GET) == | == Global Search (GET) == | ||
| + | Also visit [[stoney core: Search Resource Mapping (REST - LDAP)]] and [[stoney core: Global Searches]]. | ||
| + | |||
To form a global fulltext search (over all resources), append the url query parameter '''q''' with the desired search text: <code>https://api.example.com/v1/search?q=example</code>. | To form a global fulltext search (over all resources), append the url query parameter '''q''' with the desired search text: <code>https://api.example.com/v1/search?q=example</code>. | ||
| Line 127: | Line 128: | ||
"isCompany": true, | "isCompany": true, | ||
"isActive": true, | "isActive": true, | ||
| − | "resellerName": "Example Reseller Ltd" | + | "resellerName": "Example Reseller Ltd", |
| + | "countryCode": "CH", | ||
| + | "postalCode": "3012", | ||
| + | "localityName": "Bern" | ||
}, | }, | ||
{ "id": 4000001, | { "id": 4000001, | ||
| Line 133: | Line 137: | ||
"isCompany": true, | "isCompany": true, | ||
"isActive": true, | "isActive": true, | ||
| − | "resellerName": "Example Reseller No 2 Ltd" | + | "resellerName": "Example Reseller No 2 Ltd", |
| + | "countryCode": "CH", | ||
| + | "postalCode": "8004", | ||
| + | "localityName": "Zürich" | ||
} | } | ||
], | ], | ||
| Line 146: | Line 153: | ||
"isCompany": true, | "isCompany": true, | ||
"isActive": true, | "isActive": true, | ||
| − | "customerName": "Example Customer Ltd" | + | "customerName": "Example Customer Ltd" |
| + | "countryCode": "CH", | ||
| + | "postalCode": "3012", | ||
| + | "localityName": "Bern", | ||
| + | "belongsToResellerID": 4000000 | ||
}, | }, | ||
| − | { "id": 5000001, .. | + | { "id": 5000001, |
| + | "location": "https://api.example.com/v1/customers/5000001", | ||
| + | "isCompany": false, | ||
| + | "isActive": true, | ||
| + | "customerName": "Peter Example" | ||
| + | "countryCode": "CH", | ||
| + | "postalCode": "3012", | ||
| + | "localityName": "Bern", | ||
| + | "belongsToResellerID": 4000001 | ||
| + | } | ||
], | ], | ||
"location": "https://api.example.com/v1/customers/?q=example" | "location": "https://api.example.com/v1/customers/?q=example" | ||
| + | }, | ||
| + | "people": | ||
| + | { | ||
| + | "resources": | ||
| + | [ | ||
| + | { "id": 6000000, | ||
| + | "location": "https://api.example.com/v1/people/6000000", | ||
| + | "isActive": true, | ||
| + | "givenName": "Peter", | ||
| + | "surname": "Example" | ||
| + | "customerName": "Example Customer Ltd", | ||
| + | "belongsToResellerID": 4000000, | ||
| + | "belongsToCustomerID": 5000000 | ||
| + | }, | ||
| + | { "id": 6000001, | ||
| + | "location": "https://api.example.com/v1/people/6000001", | ||
| + | "isActive": true, | ||
| + | "givenName": "Thomas", | ||
| + | "surname": "Example" | ||
| + | "customerName": "Example Customer Ltd", | ||
| + | "belongsToResellerID": 4000000, | ||
| + | "belongsToCustomerID": 5000000 | ||
| + | }, | ||
| + | ], | ||
| + | "location": "https://api.example.com/v1/people/?q=example" | ||
}, | }, | ||
... | ... | ||
| Line 169: | Line 214: | ||
|} | |} | ||
| − | == Global Search Response Object (Resellers) == | + | == Global Search Response Object (stoney core: Resellers Resource) == |
| − | + | The logic is described on the [[stoney core: Search Resource Mapping (REST - LDAP)]] page under the chapter [[stoney_core:_Search_Resource_Mapping_(REST_-_LDAP)#Global_Search_Response_Object_.28stoney_core:_Resellers_Resource.29 | Global Search Response Object (stoney core: Resellers Resource)]]. | |
| + | Resource collection object for the stoney core: Resellers Resource. | ||
<source lang='javascript'> | <source lang='javascript'> | ||
| − | |||
"resellers": | "resellers": | ||
{ | { | ||
| Line 182: | Line 227: | ||
"isCompany": true, | "isCompany": true, | ||
"isActive": true, | "isActive": true, | ||
| − | "resellerName": "Example Reseller Ltd" | + | "resellerName": "Example Reseller Ltd", |
| + | "countryCode": "CH", | ||
| + | "postalCode": "3012", | ||
| + | "localityName": "Bern" | ||
}, | }, | ||
{ "id": 4000001, | { "id": 4000001, | ||
| Line 188: | Line 236: | ||
"isCompany": true, | "isCompany": true, | ||
"isActive": true, | "isActive": true, | ||
| − | "resellerName": "Example Reseller No 2 Ltd" | + | "resellerName": "Example Reseller No 2 Ltd", |
| + | "countryCode": "CH", | ||
| + | "postalCode": "8004", | ||
| + | "localityName": "Zürich" | ||
} | } | ||
], | ], | ||
| Line 195: | Line 246: | ||
</source> | </source> | ||
| − | == Global Search Response Object (Customers) == | + | == Global Search Response Object (stoney core: Customers Resource) == |
| + | The logic is described on the [[stoney core: Search Resource Mapping (REST - LDAP)]] page under the chapter [[stoney_core:_Search_Resource_Mapping_(REST_-_LDAP)#Global_Search_Response_Object_.28stoney_core:_Customers_Resource.29 | Global Search Response Object (stoney core: Customers Resource)]]. | ||
| + | |||
| + | Resource collection object for the stoney core: Customers Resource. | ||
<source lang='javascript'> | <source lang='javascript'> | ||
"customers": | "customers": | ||
| Line 205: | Line 259: | ||
"isCompany": true, | "isCompany": true, | ||
"isActive": true, | "isActive": true, | ||
| − | "customerName": "Example Customer Ltd" | + | "customerName": "Example Customer Ltd" |
| + | "countryCode": "CH", | ||
| + | "postalCode": "3012", | ||
| + | "localityName": "Bern", | ||
| + | "belongsToResellerID": 4000000 | ||
}, | }, | ||
| − | { "id": 5000001, .. | + | { "id": 5000001, |
| + | "location": "https://api.example.com/v1/customers/5000001", | ||
| + | "isCompany": false, | ||
| + | "isActive": true, | ||
| + | "customerName": "Peter Example" | ||
| + | "countryCode": "CH", | ||
| + | "postalCode": "3012", | ||
| + | "localityName": "Bern", | ||
| + | "belongsToResellerID": 4000001 | ||
| + | } | ||
], | ], | ||
"location": "https://api.example.com/v1/customers/?q=example" | "location": "https://api.example.com/v1/customers/?q=example" | ||
| Line 213: | Line 280: | ||
</source> | </source> | ||
| − | == Global Search Response Object (People) == | + | == Global Search Response Object (stoney core: People Resource) == |
| + | The logic is described on the [[stoney core: Search Resource Mapping (REST - LDAP)]] page under the chapter [[stoney_core:_Search_Resource_Mapping_(REST_-_LDAP)#Global_Search_Response_Object_.28stoney_core:_People_Resource.29 | Global Search Response Object (stoney core: People Resource)]]. | ||
| + | |||
| + | Resource collection object for the stoney core: People Resource. | ||
<source lang='javascript'> | <source lang='javascript'> | ||
"people": | "people": | ||
| Line 219: | Line 289: | ||
"resources": | "resources": | ||
[ | [ | ||
| − | { "id": | + | { "id": 6000000, |
| − | "location": "https://api.example.com/v1/ | + | "location": "https://api.example.com/v1/people/6000000", |
| − | + | "isActive": true, | |
| − | + | "givenName": "Peter", | |
| − | + | "surname": "Example" | |
| + | "customerName": "Example Customer Ltd", | ||
| + | "belongsToResellerID": 4000000, | ||
| + | "belongsToCustomerID": 5000000 | ||
| + | }, | ||
| + | { "id": 6000001, | ||
| + | "location": "https://api.example.com/v1/people/6000001", | ||
| + | "isActive": true, | ||
| + | "givenName": "Thomas", | ||
| + | "surname": "Example" | ||
| + | "customerName": "Example Customer Ltd", | ||
| + | "belongsToResellerID": 4000000, | ||
| + | "belongsToCustomerID": 5000000 | ||
}, | }, | ||
| − | |||
], | ], | ||
"location": "https://api.example.com/v1/people/?q=example" | "location": "https://api.example.com/v1/people/?q=example" | ||
Latest revision as of 12:51, 3 August 2014
Also visit stoney core: Search Resource Mapping (REST - LDAP) and stoney core: Global Searches.
Contents
Overview
The search resource provides a full text search over all the available resources. The available resources are:
- The main framework called stoney core is responsible for shared functionality.
- The Self-Service Modules expand the initial stoney cloud functionality.
A search could look as follows:
The following rules apply:
- The minimum number of characters for the query are 3.
- Number of entries returned per object type:
- Default: 5
- Maximum: 15 (can be raised by entries get parameter)
stoney core: search resource methods
As described above, each resource has its own search methods. The current stoney core resources are:
- stoney core: Resellers Resource - REST API
- stoney core: Customers Resource - REST API
- stoney core: People Resource - REST API
The following special resources don't have additional search methods:
Global Search (GET)
Also visit stoney core: Search Resource Mapping (REST - LDAP) and stoney core: Global Searches.
To form a global fulltext search (over all resources), append the url query parameter q with the desired search text: https://api.example.com/v1/search?q=example.
Global Search Request Message
| HTTP request part | Content | Example |
|---|---|---|
| Request lines | GET <Request-URI> HTTP 1.1 HOST: <Host> |
GET /v1/search?q=example HTTP 1.1 HOST: api.example.com |
| Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> |
Accept: application/json Accept-Charset: UTF-8 |
| Request body | <Empty> |
Global Search Response Message
| HTTP response part | Content | Example |
|---|---|---|
| Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
| Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> Location: <Location-URI> Link: X-Total-Count: |
Content-Type: Content-Type: application/json; charset=UTF-8 |
| Response body | JSON object | { ... } |
Global Search Response Message Body
| Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example
|
|---|---|---|---|---|---|---|---|
| ôbject | no | An object containing an array with one or more resource collection objects. See Reseller Collection Array Element Object for a concrete example. | { "resellers": { "resources": [ { "id": 4000000, "location": "https://api.example.com/v1/resellers/4000000", "isCompany": true, "isActive": true, "resellerName": "Example Reseller Ltd", "countryCode": "CH", "postalCode": "3012", "localityName": "Bern" }, { "id": 4000001, "location": "https://api.example.com/v1/resellers/4000001", "isCompany": true, "isActive": true, "resellerName": "Example Reseller No 2 Ltd", "countryCode": "CH", "postalCode": "8004", "localityName": "Zürich" } ], "location": "https://api.example.com/v1/resellers/?q=example" }, "customers": { "resources": [ { "id": 5000000, "location": "https://api.example.com/v1/customers/5000000", "isCompany": true, "isActive": true, "customerName": "Example Customer Ltd" "countryCode": "CH", "postalCode": "3012", "localityName": "Bern", "belongsToResellerID": 4000000 }, { "id": 5000001, "location": "https://api.example.com/v1/customers/5000001", "isCompany": false, "isActive": true, "customerName": "Peter Example" "countryCode": "CH", "postalCode": "3012", "localityName": "Bern", "belongsToResellerID": 4000001 } ], "location": "https://api.example.com/v1/customers/?q=example" }, "people": { "resources": [ { "id": 6000000, "location": "https://api.example.com/v1/people/6000000", "isActive": true, "givenName": "Peter", "surname": "Example" "customerName": "Example Customer Ltd", "belongsToResellerID": 4000000, "belongsToCustomerID": 5000000 }, { "id": 6000001, "location": "https://api.example.com/v1/people/6000001", "isActive": true, "givenName": "Thomas", "surname": "Example" "customerName": "Example Customer Ltd", "belongsToResellerID": 4000000, "belongsToCustomerID": 5000000 }, ], "location": "https://api.example.com/v1/people/?q=example" }, ... }
| ||||
error
|
object | no | In case of a failure, an error object with the appropriate error messages will be returned. Refer to the Error codes and response chapter for more informations. | error { /* ... */ } |
Global Search Response Object (stoney core: Resellers Resource)
The logic is described on the stoney core: Search Resource Mapping (REST - LDAP) page under the chapter Global Search Response Object (stoney core: Resellers Resource).
Resource collection object for the stoney core: Resellers Resource.
"resellers": { "resources": [ { "id": 4000000, "location": "https://api.example.com/v1/resellers/4000000", "isCompany": true, "isActive": true, "resellerName": "Example Reseller Ltd", "countryCode": "CH", "postalCode": "3012", "localityName": "Bern" }, { "id": 4000001, "location": "https://api.example.com/v1/resellers/4000001", "isCompany": true, "isActive": true, "resellerName": "Example Reseller No 2 Ltd", "countryCode": "CH", "postalCode": "8004", "localityName": "Zürich" } ], "location": "https://api.example.com/v1/resellers/?q=example" },
Global Search Response Object (stoney core: Customers Resource)
The logic is described on the stoney core: Search Resource Mapping (REST - LDAP) page under the chapter Global Search Response Object (stoney core: Customers Resource).
Resource collection object for the stoney core: Customers Resource.
"customers": { "resources": [ { "id": 5000000, "location": "https://api.example.com/v1/customers/5000000", "isCompany": true, "isActive": true, "customerName": "Example Customer Ltd" "countryCode": "CH", "postalCode": "3012", "localityName": "Bern", "belongsToResellerID": 4000000 }, { "id": 5000001, "location": "https://api.example.com/v1/customers/5000001", "isCompany": false, "isActive": true, "customerName": "Peter Example" "countryCode": "CH", "postalCode": "3012", "localityName": "Bern", "belongsToResellerID": 4000001 } ], "location": "https://api.example.com/v1/customers/?q=example" },
Global Search Response Object (stoney core: People Resource)
The logic is described on the stoney core: Search Resource Mapping (REST - LDAP) page under the chapter Global Search Response Object (stoney core: People Resource).
Resource collection object for the stoney core: People Resource.
"people": { "resources": [ { "id": 6000000, "location": "https://api.example.com/v1/people/6000000", "isActive": true, "givenName": "Peter", "surname": "Example" "customerName": "Example Customer Ltd", "belongsToResellerID": 4000000, "belongsToCustomerID": 5000000 }, { "id": 6000001, "location": "https://api.example.com/v1/people/6000001", "isActive": true, "givenName": "Thomas", "surname": "Example" "customerName": "Example Customer Ltd", "belongsToResellerID": 4000000, "belongsToCustomerID": 5000000 }, ], "location": "https://api.example.com/v1/people/?q=example" },
