Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
I am working on a project to provide RESTful API for a hospital related data transaction stuff. And I am using Jersey to be the server side framework for me.
However, apart from the accepted notion of dividing the code into resources, models and data access, I can't find information that provides some helpful best practices on the subject.
Any useful suggestions?
I'll try to compile some best practices that I learnt into some topics.
JPA and ORM
If you use an ORM, then use JPA. It helps to keep your ORM of choice and the application loosely coupled, i.e. you can easily switch between ORM's.
Dependency Injection
This is an awesome way, again, to keep your application as much as loosely coupled as possible. Use Guice or Spring. Basically, with this you can inject generic instances on your classes without coupling them with their concrete implementation.
Useful with DAO's. You can inject a GenericDao (interface) in your JAX-RS classes, but the true implementation of it is a JpaDao, for instance.
Also, this is awesome to quickly switch to test environments. When testing some logic in your application, you probably don't want to use the database but just a dummy implementation of your GenericDao, for example. I consider using DAO's itself as another important best practice.
Security
I have some questions about this on my profile, but basically use OAuth or HTTP Basic/Digest + SSL (HTTPS). It's a bit hard to accomplish security the way you want, surprisingly. You can use the security mechanisms your Servlet Container may provide or something internal to your application like Apache Shiro, Spring Security or even manually defining your security filters.
HATEOAS (and other REST contraints)
Most RESTful API's aren't REST. People often misunderstand this: REST implies a set of contraints. When these constraints aren't met, it's simply an HTTP API, which is also ok. In any case, I advise you to link your resource representations so that the client can navigate through your API. This is called HATEOAS and I merely scratched the surface on this matter. Please read more about REST if you want a true REST API with all its benefits.
Maven
This is a special best practice, not related to the application itself, but to its development. Indeed, Maven increases productivity a lot, specially due to its dependency management capabilities. I couldn't live without it.
I don't know if this information was useful to you. I hope it was.
If you need information about any other topic, I'll edit the answer if I know it.
In addition to the above answers, designing the resources keeping the HTTP verbs out of your base URLs, carefully selecting the #PathParam, #QueryParam, #FormParam and #FormDataParam annotations are something I strongly emphasize.
For error handling, I return a Response object with HTTP response codes to convey the error to the client calling my API.
return Response.status(<HTTPErrorCode>).entity("Error msg here or my Error Bean object as an argument").build();
Using documentation tools like Swagger API helps a lot in developer testing.
Brian Mulloy's Web API design eBook and Vinay Sahni's post had been a handy resource for me to review/correct my design.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 6 years ago.
Improve this question
The Camel Java DSL provides type-safety, code completion and proper support for refactoring. It also helps to modularize and (unit-)test your code in a great manner.
Speaking for the Camel XML syntax I only see the advantage of being able to modify and reload routes at runtime (e.g. via hawtio).
Obviously I'm really missing something here - so what is the rationale behind the use of Camel XML routes today?
In-Place editing of routes (although I would discourage doing that)
quick&dirty one-off routes (e.g. routing from test to qa environment) or very simple projects - when you have a container like karaf or servicemix. No need to fire up your IDE/compile. Just write and drop to deploy folder.
Maybe easier for non-developers
It is a matter of taste and preference.
I have used both and I have to say the java dsl is far the easier and more powerful to use.
But the best approach is to combine them, especially if you are deploying to an OSGI environment like Karaf.
Use blueprint to define your beans and routeBuilder beans and bind them. The actual implementation is done in routeBuilder classes. In blueprint you can define properties and do a few other things as well, but the actual behavior of the routes is done in java.
First off, when you say XML do you mean Spring XML DSL or Blueprint XML DSL? While they do share most of their syntax, they are not identical. Blueprint XML DSL is the preferred way of defining Camel routes for an OSGi environment (i.e. Apache Karaf runtimes) while Spring XML DSL is nowadays more or less a legacy of the times when you could only use Spring through XML.
Having said that, I think it really boils down to personal preference - a lot of developers still prefer XML over Java for defining routes and find it easier to read and follow. I myself have always preferred the Java DSL since it's more flexible and powerful but I have to admit that XML provides better overview of the routes.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 9 years ago.
Improve this question
I'm looking for some best practices for developing a clean domain object model. By 'clean', I mean a domain (or business) model that isn't cluttered up with a bunch of DB persistence, xml/json serialization/deserialization, dependency injection stuff. For example, I've read thru several 'how-to' tutorials about implementing the REST API. When they all get to the point of implementing the 'model', they all end up having some annotations about transforming from the 'pojo/poco' to the xml/json view via [XmlAttribute], or making the field be more user friendly in the UI via [Display/Display Type] attribute. The platform doesn't matter, I've seen the cluttering in the Java world (not familiar with other scripting languages).
I'm aware of the Data Transfer Object design pattern as those objects could use these attributes, but is this the only method? DTO seems like it would require a lot of object mapping to/from view to the business layer. If that's what it takes to have a clean domain layer, then great, just looking for feedback.
Thanks
The simple truth is that all of that "annotation clutter" rose up out of a rejection of all the "XML clutter".
Taking both JPA and JAXB in Java as examples, all of those annotations can be replaced by external XML files describing the same meta data for the underlying frameworks. In both of these cases, the frameworks offer "ok" defaults for unannotated data, but the truth is few are really satisfied with the Convention over Configuration default mappings the frameworks offer, and thus more explicit configuration needs to be done.
And all of that configuration has to be captured somewhere, somehow.
For many folks and many applications, the embedded meta data via annotations is a cleaner and easier to use than the external XML mapping methods.
In the end, from a Java perspective, the domain models are "just" objects, the annotations have no bearing, in general, outside of the respective frameworks. But in truth, there's always some coupling with the frameworks, and they have a tendency to influence implementation details within the model. These aren't particularly glaring, but the simple fact is that when there may be two ways to model something, and one way is "more friendly" to the framework, for many that's enough to tilt the decision to go in that direction rather than fighting for purity above the framework.
This question already has answers here:
What are Dependency Injection & Spring Framework about? [duplicate]
(10 answers)
Closed 9 years ago.
I keep seeing the phrase Dependency Injection whenever I search for Spring Framework in Google.
In plane English , can someone please explain what exactly is Spring , and why would I want
to use it ?
For example , a few days ago I've learned about Hibernate : it converts JAVA objects into records
in a DB table ... it's great , reduces the amount of code and a bunch of SQL statements .
So, how exactly does Spring helps me?
Spring is a framework which supports (among other things) dependency injection. Using Spring also makes it very easy to create web applications. Spring favors convention over configuration and was originally created as an alternative to Java EE (which was overly complex, verbose, and burdensome). But Spring is more than just dependency injection. It has core support for dependency injection, transaction management, web applications, data access, messaging, aspect-oriented programming, testing, and more.
Spring helps you by making it easy to inject dependencies, which reduces tight coupling between a class and specific implementations. For web applications, Spring follows the MVC (Model View Controller) pattern, and has specific annotations (and XML-based configuration) to help you write code that follows this pattern.
I suggest reading more about dependency injection, MVC, and the Spring framework in general to know more; there's far too much information to cover in just a single answer.
It creates loose coupling between elements due to DI. Best explanation as always by Martin Fowler
Recommended reading:
Spring in action
Official documentation
Plainer than "dependency injection"?
Let's ask what it is and why you'd use it. This is still the best explanation I know of.
Spring is more than dependency injection. It's a three legged stool:
dependency injection
aspect-oriented programming
libraries for web MVC, database, messaging, remoting, and more
There are other DI engines out there, like Guice.
If you have to ask, I'd suggest that you dig into it more before deciding.
Are there any technical Design-by-Contract solutions for Java projects similar to XINS? I'm looking for projects/frameworks that enforce developers to first author a contract for their application and then code within the boundaries of that contract, really using the contract to the full potential. I'm looking for something that, like XINS, generates code (server- and client-side, unit tests, stubs) and documentation (OpenDocument, HTML, test forms) from that contract, with a runtime component that validates the contract.
The contract can be anything, e.g. WSDL or a bunch of XML files. Integration with Spring would be nice to have.
Note that I developed XINS in the past (not the current maintainer anymore, though), and I'm wondering what similar solutions exist and how they compare.
As far as I understand Spring Web Services project promotes the approach you described. It's even described in details in their tutorial. The idea is to describe data contract manually and create web services based on this description. Spring framework provides quite a lot of different infrastructure classes to make this task much easier to solve.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
I have written a pretty extensive REST API using Java Jersey (and JAXB). I have also written the documentation using a Wiki, but its been a totally manual process, which is very error-prone, especially when we need to make modifications, people tend to forget to update the wiki.
From looking around, most other REST API's are also manually creating their documentation. But I'm wondering if theres maybe a good solution to this.
The kind of things which need to be documented for each endpoint are:
Service Name
Category
URI
Parameter
Parameter Types
Response Types
Response Type Schema (XSD)
Sample requests and responses
Request type (Get/Put/Post/Delete)
Description
Error codes which may be returned
And then of course there are some general things which are global such as
Security
Overview of REST
Error handling
Etc
These general things are fine to describe once and don't need to be automated, but for the web service methods themselves it seems highly desirable to automate it.
I've thought of maybe using annotations, and writing a small program which generates XML, and then an XSLT which should generate the actual documentation in HTML. Does it make more sense to use custom XDoclet?
Swagger is a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.
Integration guide: https://github.com/swagger-api/swagger-core/wiki
More Information: http://swagger.io/
Unfortunately, Darrel's answer is technically correct, but is hocus-pocus in the real world. It's based on the ideal that only some agree on and even if you were very careful about it, the chances are that for some reason outside your control, you can't conform exactly.
Even if you could, other developers that might have to use your API may not care or know the details of RESTful patterns... Remember that the point of creating the API is to make it easy for others to use it and good documentation is a must.
Achim's point about the WADL is good however. Because it exists, we should be able to create a basic tool for generating documentation of the API.
Some folks have taken this route, and an XSL stylesheet has been developed to do the transform:
https://wadl.dev.java.net/
Although i'm not sure it will totally fit your needs, take a look at enunciate. It seems like a good documentation generator for various web-services architectures.
EDIT Enunciate is available under github umbrella
you might be interested in Jersey's ability to provide so called WADL description for all published resources in XML format at runtime (generated automatically from annotations). This should be containing already what you need for basic documentation. Further you might be able to add additional JavaDoc, though that requires more configuration.
Please look here:
https://jersey.java.net/documentation/latest/wadl.html
Darrel's answer is exactly right. The kind of description must not be given to clients of a REST API because it will lead the client developer to couple the implementation of the client to the current implementation of the service. This is what REST's hypermedia constraint aims to avoid.
You might still develop an API that is described that way, but you should be aware that the resulting system will not implement the REST architectural style and will therefore not have the properties (esp. evolvability) guaranteed by REST.
Your interface might still be a better solution than RPC for example. But be aware what it is that you are building.
Jan
You might find rest-tool useful.
It follows language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs.
You can use it only for documenting your APIs, but this specification can immediately be used to quality assure the implementation of the real services.
If your services are not fully implemented yet, but for example should be used by a web frontend application, rest-tool provides instant mocking based on the service description. content schema validation (JSON schema) also can be easily added beside the documentation as well as used by the unit tests.
I hate to be the bearer of bad news, but if you feel the need to document the things you listed, then you probably did not create a REST interface.
REST interfaces are documented by identifying a single root URL and then by describing the media type of the representation that is returned from that URL and all the media types that can be accessed via links in that representation.
What media types are you using?
Also, put a link to RFC2616 in your docs. That should explain to any consumer how to interact with your service.