The first one is to get the single resource and the second one is to get collection resources. Because JSON format is used between a client and a backend, the efficiency is an important factor. It considers the amount of data transmitted, readability, flexibility. By considering the efficiency, there are several different ways to represent JSON format for the single resource and the collection resources.
In this style, JSON object and JSON array are utilized directly.
One main advantage of this style is to use a small amount of data to transmit. However, this doesn’t consider metadata including pagination for collection resources. The backend should return whole resources. You can easily imagine that it could be impossible once the number of resources is too many.
JSON envelope is a wrapper with a named element. The previous style has some limitation for collection resources. To solve those, JSON envelope is used to wrap the data.
With this small named element, now it is possible to send metadata including pagination.
JSON API Style
So far, pagination is mainly considered so JSON envelope is applied to collection resources. Metadata is not only about the pagination. There could be some useful information not only for collection resources but also for the single resource. One meta example is a
share_url. This style applies JSON envelope for both.
There is no right and wrong style. It totally depends on your intent and data. What I want to highlight is that knowing different styles is important to avoid common mistakes. If you choose the naive style without knowing other styles, you may need to make another API endpoint to support the pagination later.
There could be more styles and there are many efforts to make efficient APIS in JSON format. JSON API is one of them. Check their specification. You can use their library or you can learn many considerable points to make JSON format efficient.