Cross Service Search

Introduction🔗︎ click to copy

Mydex Data Services CIC provides an API known as the 'Master Reference Data Services' or MRD. This API provides access to a variety of non-personal, general purpose datasets that may be of use when integrating with the rest of the Mydex platform or simply a valuable managed API service for a range of datasets that can be subscribed to.

Each of these MRD services offer their own features, content structures. Often, these services feature their own search functionality which is specific to the items returned via that service.

Sometimes, however, it is useful to search across multiple services that you may be subscribed to. By searching for a keyword across multiple services, you may then be able to 'join the dots' between different data sets and offer a richer selection of data to your own service's members to enhance their experience.

One can imagine a citizen searching for a specific health condition, and wanting to find:

Information about the condition itself (possibly available via the MRD 'Conditions' service)
Information about medicines related to treating that condition (possibly available via the MRD 'Medicines' service)
Services or community groups in one's Scottish community that offer support to people experiencing that condition, in any number of ways (possibly available via the MRD 'ALISS' service)

Mydex offers a service known as the 'Cross-Service search' which facilitates a way to return all those items in a unified way, if you are subscribed to those MRD services already.

Authenticating with OAuth2.0🔗︎ click to copy

Mydex MRD API requires authentication using the industry standard OAuth2.0 protocol. Please see our online documentation for more information on this: https://dev.mydex.org/mrd-api/mrd-authentication.html

When requesting the Cross-Service search endpoint, you pass the same scopes to obtain an Access Token, then the Access Token itself as an Authentication: Bearer header, along with the X-Mrd-Scopes header, as you would for accessing those MRD Services already, and as is described in the link above.

What data to expect from Cross-Service search🔗︎ click to copy

To use the Cross-Service search feature, you must already be a subscriber to one or more MRD Services.

The data that is returned from the Cross-Service search will be limited to the services your OAuth2.0 client credentials are scoped for.

That means, if you are only subscribed to the 'Conditions', 'Pregnancy' and 'ALISS' services, you will not see search results that are for the 'Medicines' or 'Mental Health' services.

Please contact Mydex if you are interested in subscribing to more services to enhance the experience for your members when using the MRD.

Requesting data from Cross-Service search🔗︎ click to copy

The endpoint for the MRD Cross-Service search is https://api-mrd.mydex.org/search

The Cross-Service search feature requires the use of filters and operators in the form of query parameters. If you have used existing MRD services (be it for service-specific search or other features of that service), you should feel familiar with the syntax, but we will explain them in the following section.

Filters🔗︎ click to copy

There are different flag settings or query parameters that can be set when querying the Cross-Service search.

The filters are passed as an array filters[]. Each element in the array must contain at least 1 of both operator and value. The first filter must also have a 'keyword'. A more complex search can be performed by also passing a condition parameter (AND or OR) plus a further keyword or description (stored in the value parameter). Even if you aren't going to use a 'condition', just a single filter, you must still pass the condition query parameter with an empty value.

The structure of the array is as follows:

filters[index][option]=value

Where index denotes the index in the array starting at 0 and incrementing by 1 for each additional filter.

option refers to the parameter that must be passed and determines how the results are to be filtered. There are four possible option parameters as described in the table below.

Parameter	Description	Required?	Example
[operator]	You can use LIKE to match your sub-string as part of a greater string. You may also use '=' for an exact match.	Mandatory	LIKE
[keyword]	The keyword value used to filter the results.	Mandatory (in the first filter)	smoking
[description]	Text (a single word or a string) that can be used in conjunction with keyword to provide a more specific match.	Optional	electronic cigarette
[condition]	If we want to filter by more than one keyword we can include here AND, OR or NOT. Note: these are the only valid conditions. Note: If you are only using one filter, then this still must be declared but its value left empty.	(Mandatory but can be an empty value if not needed)	AND OR

Using a keyword🔗︎ click to copy

To request data from the Cross-Service search, the bare minimum requirement is to pass a keyword filter with an operator of your choosing, and a condition parameter, though it can be left empty if not needed.

In this example, we search for the keyword 'smoking':

https://api-mrd.mydex.org/search?filters[0][operator]=LIKE&filters[0][keyword]=smoking&filters[0][condition]=

This will return a list of items from your subscribed MRD services that contain the keyword 'smoking' in the description of the service item.

Please Remember: you will only see results for the MRD services you are subscribed to.

Using multiple keywords🔗︎ click to copy

The MRD Cross-Service search doesn't work by combining keywords in the sense of an 'AND' relationship. However, you can use an OR syntax if you want to get any results that match either (one or the other but not necessarily both) of the keywords.

In the below example, we return results for the keyword 'headache' OR the keyword 'pain'.

https://api-mrd.mydex.org/search?filters[0][operator]=LIKE&filters[0][keyword]=headache&filters[0][condition]=OR&filters[1][operator]=LIKE&filters[1][keyword]=pain&filters[1][condition]=

Drilling down on keyword results by description matches🔗︎ click to copy

It is possible to filter on the combination of the keyword and the description. This can be a useful technique to 'drill down' or filter the keyword results into more accurate results, if the word supplied for the 'description' must also match the result found for the 'keyword'.

The below example will search for the keyword 'smoking', but because we have an AND condition followed by the second filter being on description 'electronic cigarette', we limit the results.

Please Remember: your 'operator' is specific to your filter. This means you can use an 'exact' (=) operator for the keyword but use a LIKE operator for the description filter - or vice versa.

https://api-mrd.mydex.org/search?filters[0][operator]=LIKE&filters[0][keyword]=smoking&filters[0][condition]=AND&filters[1][operator]=LIKE&filters[1][description]=electronic cigarette&filters[1][condition]=

{
   "count": "1",
   "data": [
      {
        "keyword": "smoking",
        "name": "Using e-cigarettes to stop smoking",
        "description": "Find out about electronic cigarettes (e-cigarettes), including how they work and how vaping may help you quit smoking.",
        "url": "https://api-mrd.mydex.org/live-well/quit-smoking/using-e-cigarettes-to-stop-smoking/",
        "scope": "live-well"
      }
   ],
   "pagination": {
     "current_page": 1,
     "total_pages": 1,
     "next_page": null,
     "previous_page": null,
     "last_page": 1
   }
 }

Negating keywords🔗︎ click to copy

Sometimes you may search for the keyword 'pain', but this may return results that contain that string as part of a wider word, for example 'paint'.

To avoid this, you can use the NOT condition in the query, for example, searching for either 'headache' or 'pain' but not wanting keyword 'paint'.

Please Note: The 'NOT' condition negates the next filter in the query string, but is defined in the preceding filter. That's because the 'condition' at the end of, say, filter '1', is stating a condition about the filter '2' that comes after it.

https://api-mrd.mydex.org/search?filters[0][operator]=LIKE&filters[0][keyword]=headache&filters[0][condition]=OR&filters[1][operator]=LIKE&filters[1][keyword]=pain&filters[1][condition]=NOT&filters[2][operator]=LIKE&filters[2][keyword]=paint&filters[2][condition]="

{
   "data": [
      {
        "keyword": "pain",
        "name": "Swollen ankles, feet and fingers in pregnancy",
        "description": "Find out what causes swollen ankles, feet and fingers in pregnancy, what you can do to ease it, and when you need to see a doctor.",
        "url": "https://api-mrd.mydex.org/pregnancy/related-conditions/common-symptoms/swollen-ankles-feet-and-fingers/",
        "scope": "pregnancy"
      },
      {
        "keyword": "headache",
        "name": "Swollen ankles, feet and fingers in pregnancy",
        "description": "Find out what causes swollen ankles, feet and fingers in pregnancy, what you can do to ease it, and when you need to see a doctor.",
        "url": "https://api-mrd.mydex.org/pregnancy/related-conditions/common-symptoms/swollen-ankles-feet-and-fingers/",
        "scope": "pregnancy"
      },
      {
        "keyword": "headaches",
        "name": "Thrush",
        "description": "Thrush – also known as candida, candidosis or candidiasis – is a yeast infection caused by the Candida species of fungus, usually Candida albicans.",
        "url": "https://api-mrd.mydex.org/pregnancy/related-conditions/common-symptoms/thrush/",
        "scope": "pregnancy"
      },
      {
        "keyword": "pain",
        "name": "Thrush",
        "description": "Thrush – also known as candida, candidosis or candidiasis – is a yeast infection caused by the Candida species of fungus, usually Candida albicans.",
        "url": "https://api-mrd.mydex.org/pregnancy/related-conditions/common-symptoms/thrush/",
        "scope": "pregnancy"
      }
   ]
 }

Another technique to avoid false positive matches is to use the '=' operator instead of 'LIKE'. The below example will therefore also omit results with 'headaches' or 'painkiller':

https://api-mrd.mydex.org/search?filters[0][operator]==&filters[0][keyword]=headache&filters[0][condition]=OR&filters[1][operator]==&filters[1][keyword]=pain&filters[1][condition]=&page=3

{
   "data": [
      {
        "keyword": "pain",
        "name": "You and your baby at 19 weeks pregnant",
        "description": "Your baby's development and things to think about at 19 weeks of pregnancy, including pre-eclampsia, pelvic pain and keeping cool.",
        "url": "https://api-mrd.mydex.org/pregnancy/week-by-week/13-to-27/19-weeks/",
        "scope": "pregnancy"
      },
      {
        "keyword": "pain",
        "name": "You and your baby at 25 weeks pregnant",
        "description": "What's happening to you and your baby at 25 weeks of pregnancy, including baby development, your health, and planning for birth.",
        "url": "https://api-mrd.mydex.org/pregnancy/week-by-week/13-to-27/25-weeks/",
        "scope": "pregnancy"
      },
      {
        "keyword": "headache",
        "name": "You and your baby at 25 weeks pregnant",
        "description": "What's happening to you and your baby at 25 weeks of pregnancy, including baby development, your health, and planning for birth.",
        "url": "https://api-mrd.mydex.org/pregnancy/week-by-week/13-to-27/25-weeks/",
        "scope": "pregnancy"
      },
      {
        "keyword": "pain",
        "name": "You and your baby at 26 weeks pregnant",
        "description": "What's happening at 26 weeks of pregnancy, including baby development, your health, preparing for birth, making a birth plan, and vitamins and supplements.",
        "url": "https://api-mrd.mydex.org/pregnancy/week-by-week/13-to-27/26-weeks/",
        "scope": "pregnancy"
      }
   ]
 }

Pagination🔗︎ click to copy

The MRD Cross-Service search feature paginates results. The results on a single page show a maximum of 50 results.

You may work through the pages by passing the page=N query parameter, where N represents a number. The default if not specified is page 1.

To learn how many pages there are to paginate through, you can inspect the pagination element of the JSON response.

Parsing the results of the Cross-Service search🔗︎ click to copy

The MRD Cross Service search returns the matching results for your search, as a JSON Object, relative to what your OAuth2.0 client credentials can access.

Data🔗︎ click to copy

The results from the MRD services are within the 'data' key of the JSON object.

It is best to think of the results as a 'summary', akin to using a search engine. The results you see only contain basic information from the matching MRD service item, which you can inspect to obtain more information as part of other MRD requests.

They contain:

The keyword
The name of the service item
The description attribute of the service item, if applicable
The MRD URL of that specific service. To have returned an item in the result means your OAuth2.0 client is already scoped for this item. This means your application can then request this URLfrom the MRD API in the usual way to obtain the specific MRD search item in its entirety.
The matching 'scope', akin to the 'service' machine name that offers this MRD Service item.

Metadata🔗︎ click to copy

An MRD Cross-Service search result also returns some metadata about the search results.

This includes the total count of items (represented as a top-level "count" key with a single value).

It also includes a "pagination" key. This key contains the following attributes:

current_page (The page you are on)
total_pages (The total number of pages of results there are)
next_page (The next page in the pagination list)
previous_page (The previous page in the pagination list)

If there is only one page of results, the values of next_page and previous_page will be 'null'.

Each page shows a maximum of 50 results.

Errors🔗︎ click to copy

If you parse invalid or absent parameters to the Cross-Service search, you can expect to see an error key in the JSON response, with a message key contained within it.

For example, querying https://api-mrd.mydex.org/search without at least one filter will result in this response:

{
   "error": {
        "message": "You must provide at least one filter to search against"
    }
  }

Or, passing an invalid condition or filter:

{
   "error": {
        "message": "Filter option not allowed."
    }
  }

Example🔗︎ click to copy

An example of the structure of the search result is as follows. Results have been omitted for brevity.

{
   "count": "617",
   "data": [
      {
        "keyword": "smoking",
        "name": "Asbestosis",
        "description": "Asbestosis is a serious lung condition caused by exposure to asbestos – a building material used mostly from the 1950s to the 1990s.",
        "url": "https://api-mrd.mydex.org/conditions/asbestosis/",
        "scope": "conditions"
      },
      {
        "keyword": "smoking",
        "name": "What complications can affect the placenta?",
        "description": "Complications that can affect the placenta during pregnancy or childbirth include low-lying placenta, retained placenta and placental abruption. These complications are rare.",
        "url": "https://api-mrd.mydex.org/pregnancy/labour-and-birth/what-happens/placenta-complications/",
        "scope": "pregnancy"
      },
      {
        "keyword": "smoking",
        "name": "Whalsay Health Centre",
        "description": "Whalsay Health Centre can offer the following services:\r\n\r\nGeneral Medical Services\r\nChild Health Surveillance\r\nMaternity Medical Services\r\nContraceptive Services\r\nPodiatry ServicesSpecial Clinics (by appointment only)Health Visitor - Alternate Mondays (10am-4pm)\r\nPodiatry - Thursdays (9am-4pm)\r\nLong Term Conditions\r\nAnte Natal/Gynaecology (as required)\r\nHealth Improvement / Smoking Cessation\r\n\r\nOpening Hours:\r\n\r\nMonday - 8:30am - 4pm\r\n\r\nTuesday - 8:30am - 4pm\r\n\r\nWednesday - 8:30am - 4pm\r\n\r\nThursday - 8:30am - 4pm\r\n\r\nFriday - 8:30am - 4pm\r\n\r\nSaturday - 9:00am - 2pm\r\n\r\nSurgery Consulting Hours are 9am - 1pm (appointment only)",
        "url": "https://api-mrd.mydex.org/aliss/get-services/?service-ids=2940012c-5a53-44c4-9088-fd7ca2b9f84f",
        "scope": "aliss"
      }
   ],
   "pagination": {
     "current_page": 1,
     "total_pages": 13,
     "next_page": 2,
     "previous_page": null,
     "last_page": 13
   }
 }