-2

We´re developing a JSON API to deliver data to a handful of clients (namely iOS and Android Apps).

Now, the constantly arising question is: from what point of view do we structure our JSON?

1) 'Client-centric':

The JSONs keys are named after the matching UI elements in the app. e.g.:

{
    "label" : "This is a headline of a news article",
    "textField" : "This is the text of a news article",
}

Pro:

Content of the apps can be changed without releasing new versions of the app. If you wanted to change the content of the UI label, it would look like this:

{
    "label" : "This is a short abstract of a news article"
}

Also, it should be possible to have only one data model related to one view on the client side.

Contra:

Generates clutter on the server-side, as there must be the translation from data object name to UI element name

2) 'Data-centric'

The JSON keys are named after the data entity that delivers the data

{
    "articleHeadline" : "This is a headline of a news article",
    "articleText" : "This is the text of a news article"
}

Pro:

The JSON API says what it does. The key name reveals the content of the key.

Contra:

Generates clutter on the client-side, as there must be the translation from data object name to UI element name

A change in content will also change the name of the JSONs keys. 

{
    "articleAbstract" : "This is a short abstract of a news article"
}

This also requires a code change and deployment of all apps that use the API.

Which one of the two approaches do you prefer and why?

stk
  • 6,311
  • 11
  • 42
  • 58

1 Answers1

2

  1. Your API should not know how your app is implemented. It should provide a service but not know what is done with it.

  2. You should provide descriptive names for fields.

  3. The fields in the app should should be changed to descriptive names such as "articleHeadline" and "articleBody".

Update There are two levels you can look at

The Big picture - API design, dependency control, architecture

This article by Robert C. Martin (a.k.a Uncle Bob) is a great starting point. It outlines many of the issues difficulties caused by poor software design and outlines what are known as the SOLID principles of good (solid) software design. I would highly recommend reading, re-reading, and trying to fully understand it.

The Details - Method names, variable names, formatting, comments

This Book also by Robert C. Martin talks about many of the details of writing good code. It also describes what are known as "code smells" or heuristics that indicate there is likely a better solution.

cyroxis
  • 3,661
  • 22
  • 37
  • Where do these axioms stem from? Are these written in stone or can you think of a scenario where this is not the optimal solution? – stk Aug 21 '15 at 15:14
  • they are written in stone, and yes you can imagine an extraordinary scenario. – Fattie Aug 21 '15 at 15:20
  • One moment: I just thought yours and @cyroxis opinion were opposites? Did I misunderstand you both? I thought cyroxis favors 'data-centric' and you are for 'client-centric'. – stk Aug 21 '15 at 15:27
  • I updated my post with some links to provide some more detail. If you don't already know them the SOLID principles are a must. – cyroxis Aug 21 '15 at 15:47