RESTful API design


#1

So I am thinking in rewriting an API that perform CRUD operations, or at least considering learning how to design an interface that can manage properly these operations. I understand it is not only about making proper GET/POST/PULL/UPDATE calls but there is also a “proper” design logic underneath. Am I right? Could you comment on what it takes to do a proper RESTful API? There are lots of documentation and discussions in the web. I am more interested in learning your opinion on this.

Cheers,

Kf


#2

It’s funny you ask this now. I’ve been debating whether I should create a rest api tutorial recently, as part of the server tutorials I’m putting together right now.

I’m actually leaning towards not even doing a tutorial, because honestly it’s overkill for most small projects to try to create a “strict” rest api.

And like most things with programming, there are a million different ways to approach the problem. So there isn’t a one-size-fits-all solution that will work for everybody.

You have to take a step back and ask yourself, who will be using your api? Does it really need to be a “proper” rest api, or would something else make everybody’s life easier?

I wouldn’t spend too much time worrying about whether your api obeys some strict standard or not. Just worry about whether it makes sense to the people who will actually be using it.


#3

Thxs for your reply. It is too bad you are not doing the tutorial. The reason I am interested is bc of this post in the Processing forum.

I am not sure how long it will take me to figure it out. I will need to become familiar with the engine and to learn about proper restful concepts. I am definitely exploring your tutorials and doing them as time permits. I am still working in some shiffman series.

Kf


#4

I might end up writing the tutorial, I just don’t think you need to worry about making a “strict” rest api.

Are you talking about implementing something on a server, or are you talking more about calling an existing server api from Processing on the client? Or something else?


#5

I think initially I would like to work on a client API. You see, I saw shiffman’s videos on accessing data using APIs and the concept was neat as well as his demos. However, I haven’t seen the same level of flexibility in the Processing side. I have to say I haven’t worked much with the API side in processing, and you see way less comments on API calls in the forum.
APIs is one of the things I want to add under my belt this summer…

On the server side, yes… I thought about a couple of ideas but nothing terrific. More like for demonstration and experimenting with concepts. I will start with your tutorial you have for now.

Kf


#6

If you’re trying to use a rest api on the client / Processing side, then you don’t have to invent your own API on the server side. There are a ton of APIs already out there! Pretty much anything you can think of has an API, as do most websites like Spotify or Twitter.

You might not have seen much just because it’s generally easier to use JavaScript with those APIs, but it’s certainly possible to use Java to access them. You’re looking for the HttpURLConnection class.


#7

Okay, you talked me into it. Here’s a tutorial on creating a REST API: http://happycoding.io/tutorials/java-server/rest-api

I’d be very curious to hear what you think!


#8

Wow, thxs a lot! I’m probably the first one going thru your guide, no doubt. I am still buried in work for two projects and I haven’t been able to work on your material. But this guide is a must for me this weekend. Thanks a lot!

Kf


#9

Wow, it will take me longer that the time I have left today to read through your material. So, I noticed this is in your advanced section. I decided to read first about your Servlet section to become more familiar with what it was coming ahead. I do not have server experience, but I have to say that using php is about the same but it doesn’t require to compile and generate jar files or to have an strict folder layout (Servlet section). Would servlet be any better than php in certain(any) situations?

I read your concept of REST API and it is a very common way to define it. I have seen it in many places and I think at the end it is require for the user to have some server experience to fully understand the concept. I say this from a pragmatic approach, which is my approach for most cases… yes, not the most efficient… However, I find your explanation better as you start your discussion with the difference between building code for a single web application vs. different type of clients that could request the information. Then, we just need to adhere to these rules. I don’t know if it is easy to stick to those rules or if you have to break them in case the design had some initial flaw, for example it is not easy to maintain or expand (for example, instead of having people/Adam to have westSchool/people/Adam).

Those are my thoughts for tonight… More to come tomorrow if I survive work… Thxs for doing this!

Kf


#10

Languages are like tools. PHP is good for certain tasks, Java is good for others. Node.js is good in some contexts, and Ruby is good for others. Those are all languages that you can just on a server. I like to use Java because, well, that’s what I’m used to. That’s what I learned to program with, and it’s what I use at my day job. So it makes the most sense for me to stick with what I know. I chose to write a Java-based server tutorial because if you’re coming from the other tutorials on the site (starting with Processing and working your way up through Java), then sticking with Java makes sense.

Using westSchool/people/Adam instead of people/Adam is fine. That’s still a URL, so you’re still using a URL to represent your objects. A violation would be if, for example, you required the user to first submit a POST request to setPerson with data that contained Adam and then submit a GET request to getPerson to get Adam’s data. That means your requests are no longer standalone, which is a violation of REST principles.

Maybe a more likely scenario is handling logins: it’s pretty easy to use sessions to manage user logins, but using sessions is a violation of REST principles. So you have a decision: do you try to stick with a “pure” REST solution and require login information be passed with ever request, or do you go with a “REST lite” solution and keep using sessions?

There is no right answer to that question. Like I said in the tutorial, there are no REST police that will come kick your door down if you don’t obey every “rule” of REST. It’s completely up to you how strict you want to be.