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"

  • 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

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.