REST API - JSON format consistency

Question

I've been searching the web for this and haven't found an answer to a quite simple question: should JSON formats be the same for all HTTP verbs for a specific resource?

For example:

GET http://example.com/api/articles returns

[ { id: 1, ref: "21313-453542" }, { id: 2, ref: "23424-234243" }, ... ]

GET http://example.com/api/articles/2 returns

{ id: 2, ref: "23424-234243", name: "Cofee", price: 23, provider: "112-411", }

Is this a good practice or JSON objects should always keep a consistent format? To make myself clear, if the formats should be consistent the first request should return something like this:

[ { id: 1, ref: "21313-453542", name: "Oranges", price: 34, provider: "2424-12", } { id: 2, ref: "23424-234243", name: "Cofee", price: 23, provider: "112-411", } ]

What "json format" do you mean exactly? The extra properties, or wrapping it in an array? — CodeCaster
– CodeCaster, Commented May 3, 2018 at 7:06
I mean each of the elements inside the array compared to the single element. I edited the question to make it clear :-) — Pizzicato
– Pizzicato, Commented May 3, 2018 at 7:17

Riccardo Righi · Accepted Answer · 2018-05-03 07:54:35Z

In my opinion, you should use the same "schema" for the JSON data returned from the endpoints you give as example, since I would expect that the http://example.com/api/articles/2 API call can be used to obtain a single article whereas the http://example.com/api/articles can be used to obtain all the available articles, but the article data representation is the same.

If you want to provide a "compact" representation of the article entities, for example using only the id and ref attributes as in your first JSON representation, you should provide a different API endpoint, for example:

http://example.com/api/articles-refs or http://example.com/api/articles/refs

You should adopt this representation strategy for any suitable HTTP verb (for example GET, POST, PUT), while verbs such as DELETE normally requires only the id of the entity to delete, since the additional entity attributes are useless for the specific API operation.

This leads to a consistent and easy to use API, IMHO.

Anyhow, you should always document your API to provide information to the API consumers about the available operations, their semantic and the JSON schema of the input/output data.

You can use Swagger/OpenAPI for API documentation. If you use Java to implement your API, I've published ar article on DZone about this.

DavidWainwright · Accepted Answer · 2018-05-03 07:35:28Z

There are usually at least two 'views' of the same data - a summary that includes limited information that is used for returning in lists, and a detailed view that contains all the information for queries that just return the one entity. The problem with returning very detailed information in lists is that it usually involves more complex, less performant queries to the database.

So it's a good idea to split your views in this way.

Sergej Schelle · Accepted Answer · 2018-05-03 07:59:14Z

My recommendations:

The formats should be consistent. It make documentation much easier.
Replace everywhere id field with uri field. It is better if the client always sees URIs instead of ids.

For example:

{ uri: "http://example.com/api/articles/2", ref: "23424-234243", name: "Cofee", price: 23, provider: "112-411", }

Deva Gerald · Accepted Answer · 2018-05-06 13:31:05Z

Define a object pattern(generally a map) for each type of resource you have.

/api/resources (GET) - Should list all the resources

/api/resources/$resource_id (GET) - Should return a particular resource

/api/resources(POST) - Should create and return the newly created resource

/api/resources/$resource_id (PUT) - Should return the particular edited resource

/api/resources/$resource_id (DELETE) - Set HTTP 204 response code (No-Content)

Only the list resources api should give a list of objects. All the other API types can return just the object map.

Band-width optimisation : If you want to restrict the data sent to client, you can support a query parameter fields. If this field is not given, you can return the whole object representation of your resource. /api/resources?fields=id,ref

Collectives™ on Stack Overflow

REST API - JSON format consistency

4 Answers 4

1 Comment

Comments

Comments

Comments

Hot Network Questions

Collectives™ on Stack Overflow

4 Answers 4

1 Comment

Comments

Comments

Comments

Related