Difference between revisions of "stoney core: Search Resource - REST API"

From stoney cloud
Jump to: navigation, search
[unchecked revision][checked revision]
(→‎Overview)
 
(40 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
The search resource provides a full text search over all the available resources.
+
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>.
 
* <code>https://api.example.com/v1/search?q=fluffy+dragon&entries=15</code>.
  
−
* Minimum number of characters for the query are 3.
+
The following rules apply:
−
* number of entries returned '''per''' object type:
+
* The minimum number of characters for the query are 3.
−
** default: 5
+
* Number of entries returned '''per''' object type:
−
** max (can be raised by '''entries''' get parameter): 15
+
** Default: 5
−
* the attributes returned for each individual resource are presently the same as when querying the corresponding resource collection
+
** Maximum: 15 (can be raised by '''entries''' get parameter)
  
−
Visit [[stoney core: Global Searches]] for the return values per resource.
+
= 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]]
  
−
TBD
+
The following special resources don't have additional search methods:
−
* clarify number of entries (possibly rename?)
+
* [[stoney core: Authentication Resource - REST API]]
  
−
<source lang='javascript'>
+
== 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>
 +
 
 +
|-
 +
| 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 21: Line 125:
 
     [
 
     [
 
       { "id": 4000000,
 
       { "id": 4000000,
−
        "organization": "Reseller ltd.",
+
         "location": "https://api.example.com/v1/resellers/4000000",
−
        ... , 
+
        "isCompany": true,
−
         "location": "https://api.selfcare.com/v1/resellers/4000000"
+
        "isActive": true,
 +
        "resellerName": "Example Reseller Ltd",
 +
        "countryCode": "CH",
 +
        "postalCode": "3012",
 +
        "localityName": "Bern"
 
       },
 
       },
−
       { "id": 4000001, ... }
+
       { "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.selfcare.com/v1/resellers/?q=fluffy+dragon"
+
     "location": "https://api.example.com/v1/resellers/?q=example"
 
   },
 
   },
 
   "customers":
 
   "customers":
Line 33: 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.selfcare.com/v1/customers/?q=fluffy+dragon"
+
     "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 43: 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:

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:

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




Global Search Response Object



 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"
  },






								

				Retrieved from "http://wiki.stoney-cloud.org/mediawiki/index.php?title=stoney_core:_Search_Resource_-_REST_API&oldid=3831"