Difference between revisions of "stoney core: Search Resource - REST API"
From stoney cloud
[unchecked revision] | [unchecked revision] |
(→Global Search (GET)) |
(→Global Search Request Response Message) |
||
Line 64: | Line 64: | ||
|} | |} | ||
− | === Global Search | + | === Global Search Response Message === |
{| class="wikitable sortable" style="width: 100%;" | {| class="wikitable sortable" style="width: 100%;" | ||
|- | |- | ||
Line 89: | Line 89: | ||
|- | |- | ||
− | | [[# | + | | [[#global_search_response_object|Response body]] |
| JSON object | | JSON object | ||
| <source lang="javascript">{ ... }</source> | | <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 | ||
+ | |||
+ | |||
+ | |- | ||
+ | | | ||
+ | |array | ||
+ | |no | ||
+ | |An array with one or more TBD | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |<source lang='javascript'> | ||
+ | { | ||
+ | "resellers": | ||
+ | { | ||
+ | "resources": | ||
+ | [ | ||
+ | { "id": 4000000, | ||
+ | "location": "https://api.example.com/v1/resellers/4000000", | ||
+ | "isCompany": true, | ||
+ | "isActive": true, | ||
+ | "resellerName": "Example Reseller Ltd" | ||
+ | }, | ||
+ | { "id": 4000001, | ||
+ | "location": "https://api.example.com/v1/resellers/4000001", | ||
+ | "isCompany": true, | ||
+ | "isActive": true, | ||
+ | "resellerName": "Example Reseller No 2 Ltd" | ||
+ | } | ||
+ | ], | ||
+ | "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" | ||
+ | }, | ||
+ | { "id": 5000001, ... } | ||
+ | ], | ||
+ | "location": "https://api.example.com/v1/customers/?q=example" | ||
+ | }, | ||
+ | ... | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | |||
+ | |- | ||
+ | |[[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> | ||
+ | |||
+ | |} | ||
+ | |||
+ | |||
+ | |||
+ | {| class="wikitable sortable" style="width: 100%;" id="reseller_collection_array_element_object" | ||
+ | |- | ||
+ | |+ align="top" style="text-align:left;"|Reseller Collection Array Element Object | ||
+ | !Parameter name | ||
+ | !Data type | ||
+ | !Mandatory | ||
+ | !Description | ||
+ | !Valid content | ||
+ | ![http://www.pcre.org/ PCRE] | ||
+ | !Default value | ||
+ | !Example | ||
+ | |||
+ | |- | ||
+ | |<code>id</code> | ||
+ | |integer | ||
+ | |yes | ||
+ | |The identification number of the reseller. | ||
+ | | | ||
+ | |@TODO add regex | ||
+ | | | ||
+ | |<source lang="javascript">"id": 4000000</source> | ||
+ | |||
+ | |- | ||
+ | |<code>location</code> | ||
+ | |string | ||
+ | |yes | ||
+ | |The location URI of the reseller resource. | ||
+ | |@TODO add link to URI RFC | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript">"location": "https://api.example.com/v1/resellers/4000000"</source> | ||
+ | |||
+ | |- | ||
+ | |<code>isCompany</code> | ||
+ | |boolean | ||
+ | |yes | ||
+ | |<code>true</code> if the reseller represents a company, <code>false</code> if it's an individual person. | ||
+ | |<code>true</code> or <code>false</code> | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript">"isCompany": true</source> | ||
+ | |||
+ | |- | ||
+ | |<code>isActive</code> | ||
+ | |boolean | ||
+ | |yes | ||
+ | | | ||
+ | |<code>true</code> or <code>false</code> | ||
+ | | | ||
+ | |<code>true</code> | ||
+ | |<source lang="javascript">"isActive": true</source> | ||
+ | |||
+ | |- | ||
+ | |<code>resellerName</code> | ||
+ | |string | ||
+ | |yes | ||
+ | |The reseller's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand. | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript">"resellerName": "Super-duper Hosting"</source> | ||
|} | |} |
Revision as of 15:50, 14 May 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)
- The attributes returned for each individual resource are presently the same as when querying the corresponding resource collection.
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)
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
|
---|---|---|---|---|---|---|---|
array | no | An array with one or more TBD | { "resellers": { "resources": [ { "id": 4000000, "location": "https://api.example.com/v1/resellers/4000000", "isCompany": true, "isActive": true, "resellerName": "Example Reseller Ltd" }, { "id": 4000001, "location": "https://api.example.com/v1/resellers/4000001", "isCompany": true, "isActive": true, "resellerName": "Example Reseller No 2 Ltd" } ], "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" }, { "id": 5000001, ... } ], "location": "https://api.example.com/v1/customers/?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 { /* ... */ } |
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
id
|
integer | yes | The identification number of the reseller. | @TODO add regex | "id": 4000000 | ||
location
|
string | yes | The location URI of the reseller resource. | @TODO add link to URI RFC | "location": "https://api.example.com/v1/resellers/4000000" | ||
isCompany
|
boolean | yes | true if the reseller represents a company, false if it's an individual person.
|
true or false
|
"isCompany": true | ||
isActive
|
boolean | yes | true or false
|
true
|
"isActive": true | ||
resellerName
|
string | yes | The reseller's display name. Mostly the same as the organizationName or the givenName and surname out of the billingAddress object, but can also be the name of a brand.
|
"resellerName": "Super-duper Hosting" |
Resellers Search (GET)
Customers Search (GET)
People Search (GET)
{ "resellers": { "resources": [ { "id": 4000000, "location": "https://api.example.com/v1/resellers/4000000", "isCompany": true, "isActive": true, "resellerName": "Example Reseller Ltd" }, { "id": 4000001, "location": "https://api.example.com/v1/resellers/4000001", "isCompany": true, "isActive": true, "resellerName": "Example Reseller No 2 Ltd" } ], "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" }, { "id": 5000001, ... } ], "location": "https://api.example.com/v1/customers/?q=example" }, ... }