Difference between revisions of "stoney core: Search Resource - REST API"
[unchecked revision] | [checked revision] |
(→Global Search Response Message Body) |
(→Overview) |
||
(30 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 111: | Line 112: | ||
|- | |- | ||
| | | | ||
− | | | + | |ôbject |
|no | |no | ||
− | |An array with one or more resource collection objects. See [[stoney_core:_Resellers_Resource_-_REST_API#reseller_collection_array_element_object | | + | | 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. |
| | | | ||
| | | | ||
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 (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 254: | 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 260: | 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" | ||
} | } | ||
], | ], | ||
"location": "https://api.example.com/v1/resellers/?q=example" | "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": | "customers": | ||
{ | { | ||
Line 273: | 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" | ||
}, | }, | ||
− | ... | + | </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> | </source> | ||
[[Category: REST API]][[Category:stoney core]] | [[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.
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" },