3

Quick Summary

I'm building a search micro-service that will allow searching across different types of resources in a particular system (e.g. blog posts, users etc.). The API that will be exposed will be consumed by both web applications and native mobile applications.

My Solution

What I'm considering is returning an array of generic "SearchResult" objects. For example:

"results": [
    {
        "title": "My Blog Post",
        "description": "My blog post description",
        "image": "https://img.com/icon.jpg"
        "link": "https://link.com"
        "type": "blog-post"
    },
    {
        "title": "Henry Jacobson",
        "description": "Henry was born in a small village.",
        "image": "https://img.com/henry.jpg"
        "link": "https://link.com/henry",
        "type": "user"
    }
]

I think this is pretty flexible because it means that regardless of the type of resource that has been found, it'll be possible to parse it as a generic SearchResult object on the client side. This means we can return new resources in the future without having to worry about how any particular client will go about parsing them.

Sometimes, additional data might need to be provided in order to allow clients to do some custom rendering. I think this might be a good way of achieving that:

"results": [
    {
        "title": "My Blog Post",
        "description": "My blog post description",
        "image": "https://img.com/icon.jpg",
        "link": "https://link.com",
        "type": "blog-post",
        "extra": {
            "category": "Finance",
            "commentCount": "501"
        }
    },
    {
        "title": "Henry Jacobson",
        "description": "Henry was born in a small village.",
        "image": "https://img.com/henry.jpg",
        "link": "https://link.com/henry",
        "type": "user",
        "extra": {
            "status": "active",
            "topFriends": ["Jerry", "Jamie"]
        }
    }
]

Is there anything seriously flawed with this approach and if there is, what might be a better alternative?

0

The problem is that the client wont know what fields to expect for each result.

You will need to add a "_type" property to indicate the type of each result and then have documentation somewhere indicating the fields returned for each type.

The client will then have to query the _type property and be programmed with the documentation to know what to look for.

eg. Search for kittens and put all the images in one list, showing the "imageUrl" and ordered by "cutenessFactor" and all the blog posts in another list, ordered by "date" and showing the first 20 characters of "content"

| improve this answer | |
  • 2
    Thanks for the feedback, I've already included a type property in my sample responses which should address the issues you've mentioned :) – Commit May 1 '18 at 11:44
  • Why do u need the type? The type is SearchResult. SearchResult is not meant to be an input to create new resources of one or another type. It's only output. – Laiv Sep 25 at 12:45
  • in order to know what sort of "conditional rendering" to do – Ewan Sep 25 at 12:55
0

You've told that this API should return different kind of resources. Let's see some issues

  1. The representation of some searchable resource change: should you also change the representation from the search API perspective?

  2. What if you add a new kind of resource?

  3. If the client needs to separate different type of resources in different sections (eg. tabs, checkout facebook search) you need to specify which resrouce type you are retrieving and how many resources types you can have

In case 1. has no trivial solution (eg. the search microservice is different from posts microservice, so models have to be shared) don't return resources, return just links. This could introduce one more round trip from you clients, but they can cache responses (from client side), you can cache responses (from backend side) and this improves performance. Furthermore, you could add a backend aggregaton layer (or backend for frontend) to "join" data and make the search api return post instead of links back. But in this way you don't have to share knowledge of view models

To solve 2. and 3. You could just add a resourceType field in every item of you response. Take into consideration to retrieve the list of types with a GET /searchabletypes or whatever fits for you

The thing to remember is that REST is all about decoupling and navigation. Server side has its own evolution path, clients can chase them without any jump

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.