(→Search helper) |
(→Overview) |
||
(49 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | + | Also visit [[stoney core: Search Resource Mapping (REST - LDAP)]] and [[stoney core: Global Searches]]. | |
+ | = Overview = | ||
+ | The search resource provides a full text search over all the available resources. The available resources are: | ||
+ | * The main framework called [[:Category:stoney core|stoney core]] is responsible for shared functionality. | ||
+ | * The [[:Category:Self-Service Modules|Self-Service Modules]] expand the initial stoney cloud functionality. | ||
− | + | A search could look as follows: | |
+ | * <code>https://api.example.com/v1/search?q=fluffy+dragon&entries=15</code>. | ||
+ | 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: | |
+ | * [[stoney core: Authentication Resource - REST API]] | ||
− | + | == 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>. | |
− | + | === Global Search Request Message === | |
− | + | {| class="wikitable sortable" style="width: 100%;" | |
+ | |- | ||
+ | ! HTTP request part | ||
+ | ! Content | ||
+ | ! Example | ||
− | + | |- | |
− | + | | Request lines | |
− | + | |<pre> | |
+ | GET <Request-URI> HTTP 1.1 | ||
+ | HOST: <Host> | ||
+ | </pre> | ||
+ | |<pre> | ||
+ | GET /v1/search?q=example HTTP 1.1 | ||
+ | HOST: api.example.com | ||
+ | </pre> | ||
− | <source lang='javascript'> | + | |- |
+ | | Request headers | ||
+ | | <pre> | ||
+ | Accept: <Type>/<Subtype> | ||
+ | Accept-Charset: <Charset> | ||
+ | </pre> | ||
+ | | <pre> | ||
+ | Accept: application/json | ||
+ | Accept-Charset: UTF-8 | ||
+ | </pre> | ||
+ | |||
+ | |- | ||
+ | | Request body | ||
+ | | <Empty> | ||
+ | | <pre></pre> | ||
+ | |||
+ | |} | ||
+ | |||
+ | === Global Search Response Message === | ||
+ | {| class="wikitable sortable" style="width: 100%;" | ||
+ | |- | ||
+ | ! HTTP response part | ||
+ | ! Content | ||
+ | ! Example | ||
+ | |||
+ | |- | ||
+ | | Status Line | ||
+ | | <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre> | ||
+ | | <pre>HTTP/1.1 200 OK</pre> | ||
+ | |||
+ | |- | ||
+ | | Response headers | ||
+ | |<pre> | ||
+ | Content-Type: <Type>/<Subtype>; charset=<Charset> | ||
+ | Location: <Location-URI> | ||
+ | Link: | ||
+ | X-Total-Count: | ||
+ | </pre> | ||
+ | |<pre> | ||
+ | Content-Type: Content-Type: application/json; charset=UTF-8 | ||
+ | </pre> | ||
+ | |||
+ | |- | ||
+ | | [[#global_search_response_object|Response body]] | ||
+ | | JSON object | ||
+ | | <source lang="javascript">{ ... }</source> | ||
+ | |||
+ | |} | ||
+ | |||
+ | ==== Global Search Response Message Body ==== | ||
+ | {| class="wikitable sortable" style="width: 100%;" id="global_search_response_object" | ||
+ | |- | ||
+ | |+ align="top" style="text-align:left;"|Global Search Response Object | ||
+ | ! Parameter name | ||
+ | ! Data type | ||
+ | ! Mandatory | ||
+ | ! Description | ||
+ | ! Valid content | ||
+ | ! [http://www.pcre.org/ PCRE] | ||
+ | ! Default value | ||
+ | ! Example | ||
+ | |||
+ | |||
+ | |- | ||
+ | | | ||
+ | |ôbject | ||
+ | |no | ||
+ | | An object containing an array with one or more resource collection objects. See [[stoney_core:_Resellers_Resource_-_REST_API#reseller_collection_array_element_object | Reseller Collection Array Element Object]] for a concrete example. | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |<source lang='javascript'> | ||
{ | { | ||
"resellers": | "resellers": | ||
Line 26: | Line 124: | ||
"resources": | "resources": | ||
[ | [ | ||
− | { "id": 4000000, .. | + | { "id": 4000000, |
− | { "id": 4000001, .. | + | "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. | + | "location": "https://api.example.com/v1/resellers/?q=example" |
}, | }, | ||
"customers": | "customers": | ||
Line 35: | Line 149: | ||
"resources": | "resources": | ||
[ | [ | ||
− | { "id": 5000000, .. | + | { "id": 5000000, |
− | { "id": 5000001, .. | + | "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. | + | "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 45: | Line 202: | ||
− | [[Category: REST API]] | + | |- |
+ | |[[stoney_core:_REST_API#Error_codes_and_responses|<code>error</code>]] | ||
+ | |object | ||
+ | |no | ||
+ | |In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informations. | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript">error { /* ... */ }</source> | ||
+ | |||
+ | |} | ||
+ | |||
+ | == 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'> | ||
+ | "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" | ||
+ | }, | ||
+ | </source> | ||
+ | |||
+ | == 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'> | ||
+ | "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" | ||
+ | }, | ||
+ | </source> | ||
+ | |||
+ | == 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'> | ||
+ | "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" | ||
+ | }, | ||
+ | </source> | ||
+ | |||
+ | |||
+ | [[Category: REST API]][[Category:stoney core]] |
Latest revision as of 12:51, 3 August 2014
Also visit stoney core: Search Resource Mapping (REST - LDAP) and stoney core: Global Searches.
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" },