Difference between revisions of "stoney core: Search Resource - REST API"
From stoney cloud
[unchecked revision] | [unchecked revision] |
(→Global Search Response Message Body) |
(→Global Search Response Message Body) |
||
Line 113: | Line 113: | ||
|array | |array | ||
|no | |no | ||
− | |An array with one or more resource collection objects. See [[stoney_core:_Resellers_Resource_-_REST_API# | + | |An array with one or more resource collection objects. See [[stoney_core:_Resellers_Resource_-_REST_API#reseller_collection_array_element_object | Reseller collection retrieval response message]] for a concrete example. |
| | | | ||
| | | |
Revision as of 15:52, 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 resource collection objects. See Reseller collection retrieval response message for a concrete example. | { "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" }, ... }