<< Call response WebSockets in Play Framework | Home | 100 Continue support in Play >>

How to write a REST API in Play Framework

A very common question that we get on the Play mailing list is how do you write a REST API using Play Framework? There's no explicit documentation on it, you won't find a page in the Play documentation titled "Writing REST APIs". The question is often met with confusion, to those that try to answer it, the question for them is "how can you not write a REST API with Play? Play is all about REST."

So let me explain why we don't have a page on writing REST APIs. Play is fundamentally a framework for writing REST APIs, just like a fridge is a tool that is fundamentally for keeping food cold. When you buy a fridge, and you get the manual for a fridge, do you find a page titled "How to keep food cold using the fridge"? Probably not. You'll find instructions for installing the frige, turning it on, setting the temperature, adjusting the shelves, but you won't find instructions that explicitly say how to keep the food cold. Why not? Because it's assumed that you understand, when you buy the fridge, that the way to keep food cool in it is by putting food in and closing the door. The whole manual is about how to keep food cold, since that's the fridges fundamental function.

It's the same with Play. We assume first of all that you know what a REST API is. There's plenty of documentation out there on the web on what a REST API is, there's no reason for us to repeat this in our documentation, a good place to start might be this StackOverflow question. As the first answer to that question says, "Really, what it's about is using the true potential of HTTP", Play also provides everything you need to use the true potential of HTTP.

So we have documentation on writing routes in Scala and Java, we have documentation on sending results in Scala and Java, we have documentation on handling JSON in Scala and Java, and so on and so on. All this documentation is giving you the tools you need to implement what Play fundamentally about, that is, HTTP, which when realised to its true potential, will be REST. There's nothing special about a REST API in Play, writing a REST API in Play means writing a web application in the way that Play is designed to be used. We could probably rename the Play documentation home page to be "Writing a REST API in Play", that would accurately describe what most of the Play documentation is about.

Let me repeat again, Play is all about realising the full potential of HTTP, which means Play is all about REST. You want to read about how to write a REST API in Play? Read the Play documentation, it's all about writing a REST API in Play.

Tags : , , ,

Re: How to write a REST API in Play Framework

Hi james,

I agree with you're fridge exemple BUT you should check for exemple Symfony2's documentation. I was impressed by the way they explain how the framework works always by explaining the fundamental concepts you assume the user should know.

For exemple take a look to the chapter on caching : http://symfony.com/doc/current/book/http_cache.html


Avatar: Caoilte

Re: How to write a REST API in Play Framework

Hi James,

When I imagine a page telling me how to write a REST API in Play! it talks about pulling out all of the dependencies on templating engines and clientside libraries and such like. It describes how to strip a modular Play! back to the bare essentials needed for building just a REST API micro-service and nothing else. It's a fond imagining based on a Google Document roadmap eight months old. Might that be what people on the mailing list are asking about?

Re: How to write a REST API in Play Framework

I hear your point but still there are instructions (or at least suggestions) on where to put the different  foods in which fridge shelf. Telling the people that want to use Play that 'you know what you are talking about' and therefore you are not willing to help, doesn't really get you users' support. I think it would have taken you the same amount of time to write a very small example than to write the article above. There are other web frameworks out there that are offering examples.... perhaps your should consider that many potential new users may go elsewhere only because of your lack of examples.

Re: How to write a REST API in Play Framework

Thanks James. This cleared a lot up.

Add a comment Send a TrackBack