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

From stoney cloud
Jump to: navigation, search
[unchecked revision][checked revision]
(→‎Search helper)
(→‎Overview)
 
(51 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
=== Search helper ===
+
Also visit [[stoney core: Search Resource Mapping (REST - LDAP)]] and [[stoney core: Global Searches]].
−
We want to provide an omni-search/ElasticSearch style search function and the most flexible approach is by doing the search completely on the server-side.
+
  
−
Therefore we are gonna copy the leader in search and define the URL for searching this way (see [https://blog.apigee.com/detail/restful_api_design_tips_for_search]):
+
= 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.
  
−
<code>https://api.example.com/v1/search?q=fluffy+dragon</code>.
+
A search could look as follows:
 +
* <code>https://api.example.com/v1/search?q=fluffy+dragon&entries=15</code>.
  
−
We already have a generic [[#Filtering.2C_sorting_and_searching|full-text search]] mechanism defined for all resources. Why not use the same mechanism but apply it on the root resource (<code>https://api.example.com/v1/?q=fluffy+dragon</code>), this way we don't have to break the REST principal (method versus resource). The search will then return simple JSON objects with a type and a location URI. The actual resources on which to apply the search filter, will be defined on the server side  --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 15:24, 16 December 2013 (CET)
+
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)
  
−
Reseller search example: <code>https://api.example.com/v1/resellers/?q=fluffy+dragon</code>. TBD. Diese Variante beschreiben.
+
= 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]]
  
−
* number of entries returned '''per''' object type:
+
The following special resources don't have additional search methods:
−
** default: 5
+
* [[stoney core: Authentication Resource - REST API]]
−
** max (can be raised by appropriate get parameters): 15
+
  
−
<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 20: 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.selfcare.com/v1/resellers/?q=fluffy+dragon"
+
     "location": "https://api.example.com/v1/resellers/?q=example"
 
   },
 
   },
 
   "customers":
 
   "customers":
Line 29: 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 39: 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"