I am learning about REST apis and after some time of researching, I know the basics of how REST works and I can write an api that generates a JSON response in the web browser with appropriate url. However, I can't seem to understand what is the purpose of it. Surely just generating JSON response seems useless for production application, as you have to assume that most of your website visitors won't even know what JSON is, so there must be some other uses of rest api that I still don't know about. I have been searching a lot about why I should use a rest api, but besides websites praising it ("because it is scalable, portable, flexible" and so on and on) and saying that JSON is simpe yet powerful data exchange format, I have found no concrete answer.

As of this particular case, I am learning to develop RESTful api with Spring. I understand simple CRUD actions using @RestController, but It seems ridiculous to just sent JSON object as a response and especially to expect a client to understand JSON data.

So I am guessing that there must be some other uses for RESTful api that I am not aware of and can't seem to look up either.

So my questions are:

1. Why should I write RESTful controller if all it does is generate JSON data as a response.

   1.1) I am assuming that it IS NOT all it does, so why is it necessary exactly?

2. Where and what should I use JSON data for?

I know that I am far from understanding this fully, so there probably are many misconceptions, but I want to understand the reasoning behind everything I do and not blindly follow whatever studying resources say, so I am asking it here. Thank you for your time

CodePudding user response：

Its very important to understand that API (yeah, capital letters are quite important) is acronym for Application Programming Interface, it is not user interface, it is interface for other programs/applications to use.

So, API will be used solely by some other code to exchange data (interface with each other) and to do this you need some structure or protocol to follow by both side of this exchange, otherwise applications will not understand each other.

So, you decided that your application (service) will provide some API for other applications (again, not users), you decided what kind of functions those applications will be able to consume (like get current weather, or create new user - basically methods in your controller).

Next step is to define protocol - how exactly information will be presented on wire (serialized to binary stream, because you can send only bytes via physical connection), JSON is quite popular choice because it provides quite easy format to parse for application (libraries for JSON exist for almost any programming language), but also is still readable enough for humans (there many offline and online formatters to help you).

But, JSON is not most efficient in terms of space, this is why you can pick many others - BSON, protobuff, kryo, java RMI and so on.

Now, lets actually answer you questions:

Why should I write RESTful controller if all it does is generate JSON data as a response.

Because you as developer decided to provide API for others, and you decided to use JSON as data format, and you decided so (probably) because it is quite famous and easy to work with, it is provided by default in many frameworks, etc, but there is no real objective reasons for that, several years ago SOAP/XML was holding the same niche, for the very same reasons.

Where and what should I use JSON data for?

Anywhere and for everything where you think it will fit: non performance critical inter-service communications, config files, personal notes, structured or non structured data, JSON is very flexible format (as almost any other generic purpose one, like XML or simple text files).

CodePudding user response：

A ReST API will usually be called by another service or e.g. by a JavaScript based frontend application, not directly by users. JSON can be processed quite comfortably by other applications, that's why it's widely used (by now there are other formats as well, especially for high performance applications, but that's on an advanced level).

So to your questions specifically: If you are offering a service, that will be used by other applications, then use a ReST API with JSON responses, if you are offering an application that will be used by users directly, and don't want to have a JavaScript frontend application, you would use something like Thymeleaf to implement the frontend and have that returned in your controllers.