Spring RESTful best practice - example/tutorial needed [closed]

Question

SHORT STORY: I'm looking for tutorial or a github project that has an example of RESTful service design "best practices".

LONG STORY: I'm going through the "official" Spring tutorial for designing and implementing web services: http://spring.io/guides/tutorials/rest

It has an example of a small project. They are using "hexagonal architecture" and a bunch of "event" classes for this project. Going through it, I can't help but note that it seems way too over-engineered, for an example project. There are over 50 classes, not counting the tests. Is this really the "best practice" example of such a service? If not, are there any other examples that are better?

Answer 1

I cannot point you to a tutorial, but can mention some things based on experience with writing RESTful services using Spring MVC.

1. split the Controllers from the business logic. Concerns to have in the Controllers: most of all error handling, also potentially authorization. The Controller methods might be quite thin initially, and just dispatch to corresponding business logic methods. That's not a bad thing, soon your Controllers will grow with issues of interfacing clients.

2. speaking of error handling, it is quite hard to get it right in a RESTful service. You definitely need to have a way to nicely inform the clients of errors, via structured data. That should be a part of all your responses, I guess. You will need to decide which errors you send back info about, which ones you are silent about and just log, etc.

3. most probably you will have some data objects for the requests you are getting, and the responses you are sending. Package them in a separate jar. Add to this jar interfaces, implemented by your Controllers. Add also a simple second implementation of these interfaces, that makes calls to your service. Here you go, you have a client lib. Distribute it, make your Java clients happy.

4. Even though now you have a nice Java client lib, do not forget to also test your service with curl, and document how to use it this way, with simple calls. Make your non-Java users happy.

5. There are all kinds of libs for "unit" testing Controllers, by mocking up more or less of the internals of a web server. These are very useful, but do not limit yourself to them. Have a qa env, where you fully deploy your service, and have a qa app which sends real fully fledged requests to the instance of your service on the qa env, and analyses their responses.

6. Try to keep things simple and consistent across the different calls. For example every response can contain the same "error" part with the same fields giving information in a structured programatically usable form about what went wrong.

7. REST is a nice abstraction, but has its limitation: in practice, /delete.json?id=3 can have very different effects on different services. Do not expect your clients to be able to guess what "add" and "delete" will mean in your particular case, as they will probably guess differently from what you expected. Instead, provide in your documentation some information about what your service will be doing under the hood. We are not yet at a stage where we are able to have components communicating via the knowledge of just a very thin interface, staying agnostic of their internals, unfortunately.