How to link the response of a rest call with my request?

Question

I have a service that makes a request for data from another, and it can be a list like so:

POST /getFavoriteNumber

{
    "persons": [
        {
            "name": "joe",
            "birthdate": "01/01/2000"
        },
        {
            "name": "jane",
            "birthdate": "01/01/2000"
        }
    ]
}

And the response is something like:

{
    "persons": [
        {
            "birthdate": "01/01/2000",
            "favColor": 22
        },
        {
            "birthdate": "01/01/2000",
            "favColor": 12
        }
    ]
}

How would I be able to link back to find what joe's favorite color is? Should I introduce an id that is created by the caller?

Answer 1

Purely from a REST perspective, you'd make this accessible per person, so you always know which result belongs to which person:

api/people/123/favoritecolor
api/people/456/favoritecolor

However, because you are presumably relying on the name and birthdate combination, this becomes more difficult to keep clean. Nothing is stopping you from doing the same:

api/people/joe/2000-01-01/favoritecolor
api/people/jane/2000-01-01/favoritecolor

...but you can see how that quickly grows out of proportion depending on how complex your identifier is.

You'd generally expect your resourced to have some sort of unique identifier so that they can be easily referenced. You currently don't have this, and I'm not sure why.

If possible, I would strongly advise to start using UIDs to significantly simplify the data references.

---

If you don't use a UID, since in your current case the combination of a name and a birthdate uniquely identifies the person, so you can use those values in the result to uniquely identify the person whose favorite color this is:

{
    "people": [   // the plural of "person" is "people" :-)
        {
            // Identifies the person
            "name": "jane",
            "birthdate": "01/01/2000",

            // Lists the requested result
            "favColor": 22
        },
        {
            // Identifies the person
            "name": "joe",                
            "birthdate": "01/01/2000",

            // Lists the requested result
            "favColor": 12
        }
    ]
}

---

Alternatively, you could add that arbitrary id value that the consumer themselves chooses and adds to the request, but I don't quite see this as being the better option here.

Answer 2

This is not stricitly related to microservices though, it's more a general question about good RESTful design (and a POST /getSomething API is a little far from good RESTful design :) )

in the most of cases, query API just retrieve single resources by ID o lists based on a filter ( all people which favorite color is "yellow"). There are other useful cases where you combine multiple "get by id" into one call. In this case you can use a GET and pass a list of ids in the request URL

GET /persons/favouritenumbers?ids=1,2,3

[{
    id:1,
    color:'blue'
}

...

]

Now, your requirements may led you to use a pair username/date of birth as primary key, but this will make your life worse when you have to expose that data with http API. This is true especially in a microservices environment, where sharing of ids through subdomains in fundamental to achieve a correct information modeling across the components. So yes, adding an ID is the best thing you could do