6

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

  • Maybe I'm just dumb, but that JSON API seemed to make no sense to me. With that said, there is also JSON-RPC which is pretty simple jsonrpc.org/specification which may be a good alternative. – whatsisname May 29 '16 at 3:12
5

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.

3

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.

  • I am evaluating json api specification for our internal api's which are used for communication between the backend and frontend. Based on your reply, I shouldn't be using it. I would like to understand the advanced cases and the complication that json api specification brings which I didn't come across while glancing through the specification. Could you please share some details? Thanks ! – Andy Dufresne Mar 7 '18 at 5:50
0

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.

  • 1
    The point of the Json API spec has nothing to do with code gen. It has to do with self describing and discoverable APIs. (Providing links to relevant resources in your response.) It seems to be very similar to the hal+json spec and you can find a great explanation of the concepts in this presentation from Stefen Tilkov – RubberDuck May 28 '16 at 15:46
0

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.

  • That looks like an interesting video, but what does it have to do with dynamically generating JSON API's? Discovery is all well and good, but don't you still have to support the new JSON fields in your server software anyway? – Robert Harvey May 28 '16 at 18:40
  • It doesn't @RobertHarvey, but neither does the question. The point is simply that developing against the Json API spec (or the hal+json spec for that matter) allows you to develop very generic (dumb) clients that basically handle whatever you throw at them. Leaving the decisions about what actions can be taken to the server. It can be a more flexible approach, but isn't for every use case. – RubberDuck May 28 '16 at 18:45
  • There's no way you can write a client that magically gains new features when you add new JSON fields. You just shift that logic somewhere else, probably to the UI layer in the particular example you've provided with purchase, and that part has to be updated. Plus, this approach is only applicable when UI exists, which is not the case for many web services' clients. – Haspemulator Jul 3 '17 at 10:58
  • @Haspemulator "If you've built your client(s) to just display all of the possible actions (links)" then yes, you can add new functionality simply by adding new data (an action url) to your response. I'll admit, I don't know how to write something that generic for Android, but it's done all the time on the web. – RubberDuck Jul 3 '17 at 11:27

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.