Search APIs

Two search APIs are used in the MDM and Cloudant® integration sample: Search by Display Name and Search by Last Name. Search APIs differ from the retrieve APIs in that various search criteria are supplied by the client and that the criteria might match zero or more instances.

Because the search parameters themselves can, in the aggregate, identify a party, supplying them in a GET url can lead to a PII (personally identifiable information) violation. The MDM and Cloudant sample service therefore requires these APIs to be started with an HTTP POST verb.

For more information about these APIs, see the Pagination description at the end of this topic.

Search by Display Name

A client can retrieve all person instances that match a display name through the /search/person API.
curl -i -X POST -H "Accept: application/json" http://127.0.0.1:4800/mcs/search/person/?name=xxx
Display name is defined as the concatenation of the first and last names. For example, "John Doe", and corresponds to the TCRMPersonBObj.DisplayName property in the person JSON documents.
The service invocation runs an exact and case-sensitive match of the query parameters against the database. The service responds as follows.
  1. If no party instance has a display name that matches the supplied parameter, return a 404 HTTP RC and an empty array as the payload.
  2. If an error occurs, return a 400 HTTP RC and a hash with an error property.
  3. Otherwise, return a 200 HTTP RC and an array whose elements are valid PartyId values for the person instances that match the query.

Search by Last Name

A client can retrieve all person instances that match a last name through the /match/person API.
curl -i -X POST -H "Accept: application/json" http://127.0.0.1:4800/mcs/match/person?last_name=xxx
The service invocation runs an exact and case-sensitive match of the query parameter against the database. The service responds as follows.
  1. If no party instance has a display name that matches the supplied parameter, return a 404 HTTP RC and an empty array as the payload.
  2. If an error occurs, return a 400 HTTP RC and a hash with an error property.
  3. Otherwise, return a 200 HTTP RC and an array whose elements are valid PartyId values for the person instances that match the query.

In addition to pagination parameters, clients can specify an extra include_docs parameter whose valid values are true or false. The default is set to false. When set to true, the API returns the stored JSON documents as array elements instead of only the PartyId String.

Pagination

By default, the MDM and Cloudant sample service sets default values for the following parameters. Because of the default setting, these parameters are optional unless the client needs to override the default values.
  • limit: The maximum number of query results that are returned per request, defaults to 25.
  • skip: Skips the first n results, defaults to 0.

If a client wants to iterate over all the matched persons in the database, it must retrieve over this set in "pages" by directing the server to "skip" over previously returned instances when subsequent requests are issued.


Last updated: November 6, 2015