JSON API or Plain JSON

Question

There is a debate in my company on whether we should use the JSON API specification or stick to plain JSON for developing APIs that will be consumed by mobile apps, mainly iOS and Android.

One argument for JSON API is that since everything is defined before hand, if new developers were to begin work on the API they should be able to find what they need fast. Another is that since most of the relationships can be bundled to a response, it can relieve server load.

One argument against JSON API is that it creates problems that didn't exist before. When using plain JSON there are attributes that hold relationships or objects of the same type e.g: If I where to have a novel with holds information on the author and publisher the plain JSON would be something like that:

{
    author: { 
                name: "John",
                lastname: "Appleseed",
                id: 1
            },
    title: "Some great novel",
    publisher: {
                   name: "Something"     
               }
}

and then, on Android I could create a class to serialise the JSON. The class would be something like that

class Novel {
    String title;
    Author author;
    Publisher publisher;
}

class Author {
    String name;
    String lastname;
    int id;
}

class Publisher {
    String name;
}

and then Retrofit would parse the response and return a Novel POJO.

In Swift, we could use SwiftyJSON and create some similar structs or classes with the only difference being that I would have to write some extra boilerplate code to set the values of the class. This seems like a straightforward approach.

But when using the JSON API implementation will become much more complex and unreadable.

Regarding the argument that it relieves server load since it can bundle most relationships and return them with the response you can achieve that with plain JSON as in the example above.

I could use some insight on whether it is a good choice to use JSON API with statically typed languages such as Java or Swift

Answer 1

I'm not interested in JSON, I'm interested in the objects that are created from JSON. Like in your example, turning plain JSON into objects is easy. How difficult is it for new developers? Mostly they are interested in the objects created. They can look at the code that turns JSON into objects, which is trivial.

I looked at the JSON API spec, and I wouldn't recommend it to anyone but a masochist.

Answer 2

JSON API is nice, but complex spec. Its implementation is also not easy, especially if you don't have good library implementing it.

So it's mostly a question "is it worth it for our use case"?

In my opinion, it's worth it if you have large and/or public API which needs to be stable, extensible, will be developed for years. JSON API provides reasonable standard for APIs (so you don't need to create your own one), has covered a lot of advanced cases (which you don't even think about now, but will cause you problems later), has existing implementations in many languages and platforms and has public, well defined specification, existing support and userbase etc.

It's not worth it, if it's a private API between one client and one server which might be completely reworked in a year or so, worked on by a small team.

Of course, there's many projects lying somewhere between these rather extreme cases, where the decision might not be easy.

Answer 3

I'm currently dealing with a SOAP API and it's corresponding WSDL. After looking over the JSON API specs. I get the impression that they are trying to be a WSDL equivalent for REST JSON servers.

Like WSDLs, the JSON API is not the most readable in the world (although more readable than WSDLs,) but is meant to be parsed by tools that will then create the necessary code for you.

Converting JSON to swift structs requires a lot of boilerplate code. Sure it's readable, and easy to create that code, but it's quite tedious and time consuming. A waste of time when an automated tool can do the job.

That said, SOAP and WSDLs are becoming extinct, and I think a big part of why has to do with the code the automated tools create... The code generated is itself usually hard to read, and a pain to manually update.

Of course the whole point of auto-generated code is that you don't have to update it, but having that hunk of garbage code in the middle of your pristine base is difficult to stomach.

Sometimes aesthetics are more important than efficiency.

Answer 4

Would you like to be able to dynamically add new content and functionality to your client without having to change it? If you go with Json API (and actually leverage it), you can accomplish exactly that.

Let's say v1 of your book resource looks like this

links: { 
         self: "/books/1"
          next: "/books/2"
}
author: { 
            links: {
                 self: "/authors/1"
            }
            name: "John",
            lastname: "Appleseed",
            id: 1
        },
title: "Some great novel",
publisher: {
               name: "Something"     
           }

Then you decide to add the ability to purchase.

links: { 
         self: "/books/1"
          next: "/books/2"
          purchase: "/books/1/purchase"
}

If you've built your client(s) to just display all of the possible actions (links), then you've just added the purchase functionality to all of your clients, simply by updating what gets returned from your server.

I highly recommend watching Stefen Tilkov's talk: REST: I don't Think it Means What You Think it Does.