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

From stoney cloud
Jump to: navigation, search
[unchecked revision][unchecked revision]
(→‎Global Search Request Response Message)
(→‎Global Search Response Message Body)
Line 113: Line 113:
 
|array
 
|array
 
|no
 
|no
−
|An array with one or more TBD
+
|An array with one or more resource collection objects. See [[stoney_core:_Resellers_Resource_-_REST_API#Reseller_collection_retrieval_response_message |  Reseller collection retrieval response message]] for a concrete example.
 
|
 
|
 
|
 
|

Revision as of 15:51, 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 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 { /* ... */  }











Reseller Collection Array Element Object



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




								

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