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

From stoney cloud
Jump to: navigation, search
[unchecked revision][unchecked revision]
(→‎People Search (GET))
Line 170: Line 170:
  
  
 +
== Global Search Response Object (Resellers) ==
  
−
{| 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
 
  
−
|-
+
<source lang='javascript'>
−
|<code>id</code>
+
{
−
|integer
+
  "resellers":
−
|yes
+
  {
−
|The identification number of the reseller.
+
    "resources":
−
|
+
    [
−
|@TODO add regex
+
      { "id": 4000000,
−
|
+
        "location": "https://api.example.com/v1/resellers/4000000",
−
|<source lang="javascript">"id": 4000000</source>
+
        "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"
 +
  },
 +
</source>
  
−
|-
+
== Global Search Response Object (Customers) ==
−
|<code>location</code>
+
<source lang='javascript'>
−
|string
+
  "customers":
−
|yes
+
  {
−
|The location URI of the reseller resource.
+
    "resources":
−
|@TODO add link to URI RFC
+
    [
−
|
+
      { "id": 5000000,
−
|
+
        "location": "https://api.example.com/v1/customers/5000000",
−
|<source lang="javascript">"location": "https://api.example.com/v1/resellers/4000000"</source>
+
        "isCompany": true,
−
 
+
        "isActive": true,
−
|-
+
        "customerName": "Example Customer Ltd"      
−
|<code>isCompany</code>
+
      },
−
|boolean
+
      { "id": 5000001, ... }
−
|yes
+
    ],
−
|<code>true</code> if the reseller represents a company, <code>false</code> if it's an individual person.
+
    "location": "https://api.example.com/v1/customers/?q=example"
−
|<code>true</code> or <code>false</code>
+
  },
−
|
+
</source>
−
|
+
−
|<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>
+
−
 
+
−
|}
+
−
 
+
−
== Resellers Search (GET) ==
+
−
 
+
−
== Customers Search (GET) ==
+
−
 
+
−
== People Search (GET) ==
+
  
 +
== Global Search Response Object (People) ==
 +
<source lang='javascript'>
 +
  "people":
 +
  {
 +
    "resources":
 +
    [
 +
      { "id": 5000000,
 +
        "location": "https://api.example.com/v1/customers/5000000",
 +
        TBD
 +
        TBD
 +
        TBD
 +
      },
 +
      { "id": 6000001, ... }
 +
    ],
 +
    "location": "https://api.example.com/v1/people/?q=example"
 +
  },
 +
</source>
  
  
 
[[Category: REST API]][[Category:stoney core]]
 
[[Category: REST API]][[Category:stoney core]]

Revision as of 16:00, 14 May 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)
  • 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:

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




Global Search Response Object



 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 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"
      },
      { "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 { /* ... */  }









Global Search Response Object (Resellers)


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


Global Search Response Object (Customers)


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


Global Search Response Object (People)


  "people":
  {
    "resources":
    [
      { "id": 5000000,
        "location": "https://api.example.com/v1/customers/5000000",
        TBD
        TBD
        TBD
       },
      { "id": 6000001, ... }
    ],
    "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=3428"