Should a RESTful API return data with codes or translate codes into descriptions?

Question

I'm developing an API that will return data to an end user. In my server side model, I use a number of codes that have an associated lookup table to find descriptions and other related properties tied to the code.

I'm curious if there is a "Best Practice" in regards to returning data. The options here would be:

Option 1: Return codes and provide APIs for lookup lists

In this scenario, you might have something like this:

//An API call to get a person
let person = await this.dataService.getPerson(1); //performs fetch
//{id: 1, first: "Micky", last: "Mouse", gender: 1, countryOfOrigin: "US"}

//An API call to get lookups -- returned as Map();
let genders = await this.dataService.getGenders();
let countries = await this.dataService.getCountries();

//Now I can do the following to get the definition
let gender = genders.get(person.gender);
let country = countries.get(person.countryOfOrigin).description;

 console.log("gender.description");
 console.log("country.description");
 console.log("country.isoA3");

Option 2: Return an object fully populated

//API call to get a person
let person = dataService.getPerson(1);
//{id: 1, 
   first: "Micky", 
   last: "Mouse", 
   gender: "Male", 
   countryOfOrigin: {
      code: "US",
      description: "United States of America",
      isoA3: "USA",
      isoN3: 840
    }
  }

Option 3: Make it self referencing

I know there is an option whereby the countryOfOrigin might be a link to another API call for a given country. However, in my situation, most users will be requesting a large number of people as opposed to individual people and displaying those persons in a list form -- so it would be quite a hit on the server if the user had to query for 1000 people and then ping the server 1000 times to get each countryOfOrigin.

Is there a standard or best practice that would provide some direction here?

Answer 1

Is there a standard or best practice that would provide some direction here?

Not really, there are just different trade offs.

The easiest analogy I can think of on the web is java script -- should you embed the source in the page? or should you link to the source and download it separately? "It depends" -- having the separate resource is great when you want fine grained control of the caching policy, but its lousy when caching is a liability rather than an asset.

One common approach, as noted by Preacher, is to provide different resources for the different use cases.

Another possibility is to use a single resource, but with different representations (media-types) to support the different use cases.

As far as I can tell, these are just different ways of moving the pain around.

Answer 2

You have a couple of potential options:

A. Use an api standard that supports embedding resources.

I tend to use HAL for all responses, but HAL is not a great format to solve this problem. JSON:API handles this case better. It allows sending relationships along with the response, an a good JSON:API client can take those relationships and put them in a temporary cache.

The reason HAL isn't good for this is that it doesn't have a good way to de-duplicate multiple relationships. GraphQL handles this case also extremely well, but it's not REST.

B. Attack the true cause of the issue.

Really the issue you are describing is that you are worried that many HTTP requests will be made, and having many HTTP requests is a bad thing.

There's several ways to potentially combat this.

1. Use HTTP/2. With HTTP/2 having many smaller requests is much less of an issue as it used to be. Maybe it's not as painful as you think.
2. Use HTTP/2 Push. Push can optimize this a little bit further and remove even a bit more latency.
3. If your API is slow, choose a technology that can respond to HTTP requests even faster. Does your framework have a 100ms start-up time for every request? That's gonna be very noticable.
4. Use great cache headers. Countries don't change much. You can put very aggressive Cache-Control headers, letting clients keep a copy of the headers for a very long time. This will especially benefit browser clients (HTTP clients running on servers tend to not use caching much).
5. Use a good caching proxy or CDN. This is related to 4, and might make 3 unnecessary.