REST API resources and JSON structure design

by mcd   Last Updated January 06, 2018 06:05 AM

We are creating REST API which will be consume by Web and Mobile users.

My uestion is do we need to consider user interface before designing JSON structure?

For example,
We have one resource Company, and Company has multiple customers with its experiances.
we created API company/{company_id}/customers to fetch list of customers for particular company. In response of API, we are sending list of customers with basic detail like (id, name, address, email, phone).

Is that a best practice to send customer experiences with customer detail?
currently while fetching customers we are sending only basic detail of customers without their experiences.

when we reffer user interface for mobile and web its showing customer's experience with customer detail in customer listing screen.

so now is that a best practice if we make multiple small rest calls to get other information ?

please can you guide us.
Thank you in advance.

Answers 1

I do not regard sending various details together with main data by default as a good practice. Instead, use some option with name like _with to list all child entities you want to get in an API response. For your example it might be something like: company/{company_id}/customers?_with=experience,purchase

Usually I try to map _with items to my domain model (Customer is a main entity, Experience and Purchase are related to it).

I do not recommend using small REST calls to fetch details because of performance reasons. REST call is an expensive thing.

Vladislav Rastrusny
Vladislav Rastrusny
January 06, 2018 08:44 AM

Related Questions

Designing a flexible search API response

Updated May 01, 2018 11:05 AM

null vs missing key in REST API Response

Updated May 26, 2015 22:02 PM

JsonAPI - Updating the relationship for a resource

Updated February 25, 2016 01:02 AM

GET resource state with JSON body or HTTP code

Updated June 19, 2016 08:02 AM