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.
Related
I'm trying to generate swagger documentation for a Vert.X Reactive application. The current solution is a static YAML file that is converted to an openapi.json file.
This is an awful lot of work and I'm wondering if there is a way to do this automated. I know there are solutions to do it the other way around, but because it is an existing application this is not a possibility.
I found the following library: https://github.com/outofcoffee/vertx-oas Which is kind of the direction I want to go but sadly isn't up to date.
I expect it to be possible but I'm a little bit stuck right now.
vertx-web-api-contract mantainer here. Unfortunately, we have no official solution for Vert.x Web to OpenAPI conversion because of the design of Vert.x Web Router APIs.
Starting from the Router there is no way to infer what are the request parameters, their location in the request, their schema, if they are required or not, their style, etc. The same thing applies for response bodies where you can't infer the body schema.
Jax-rs and similar technologies allow this conversion because they describe the request contract using some declarative API (e.g. annotations), so a converter just needs to read this description to translate it to the OpenAPI contract
Francesco
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.
I know there are a few questions regarding the libraries you can use to do RESTful services in Java, but what is the value in using them against vanilla implementations. I mean, if i was looking to create the url structure described by Wim
www.example.com/images
www.example.com/images/id/num
www.example.com/images/tag/num
www.example.com/images/tag/num/num/num
Would it not be easier (for future developers) and faster (to implement and learn) to map the url pattern /images to a servlet and have a line or two that parses the url for the parameters instead of learning, implementing and configuring one of these libraries to do it for you.
Apache CXF
Jersey (popular)
Restlet (pioneer of JAX-RS)
RESTEasy
Essentially what I am asking is... What is the value in using a RESTful Java framework? Would it not be adding a lot of complexity, in the implementation, for a simple problem?
EDIT: This jersey code is handled very neatly and everyone should know how to do it in servlet form if they are looking into libraries to do it for them.
#Path("/helloworld")
public class HelloWorldResource {
// The Java method will process HTTP GET requests
#GET
// The Java method will produce content identified by the MIME Media
// type "text/plain"
#Produces("text/plain")
public String helloWorld() {
// Return some cliched textual content
return "Hello World";
}
}
If all you are going to be doing is a "service" that returns text that is driven by URL parameters, so plain text returns, is a framework necessary?
Would it not be easier (for future developers) and faster (to implement and learn) to map the url pattern /images to a servlet and have a line or two that parses the url for the parameters instead of learning, implementing and configuring one of these libraries to do it for you.
…
Easier? It's certainly not easier to write — you've got to do all the path extraction yourself and all the method handling and all the content type negotiation (in both directions) and all the cookie handling and the object deserialization/serialization thunks and … well, lots of low-level stuff that would all need testing and debugging — or easier to maintain either, since the JAX-RS interface lets you operate at the level of resources (the natural characterization of RESTful webapps) instead of requests; with much experience, maintenance is easiest when the gap between conceptual model and implementation is smallest. It's also not faster to implement (because the low-level implementations of JAX-RS have already been tested and debugged for you; less for you to do) and the cost of learning it isn't very high as it is a mostly declarative API with very few surprises.
OK, these benefits might not seem so much when you're only dealing with simple webapps. After all, you can hack something out in very little time and put the resulting lash-up online. You'll then have to pray that you got it right without significant unexpected avenues for exploits or denial-of-service attacks. And the maintenance programmers will have to understand just what those regular expressions you've sprayed through the code do (Good Luck With That!) when adding small features or fixing bugs. But as the webapp gets larger, the benefit of having a tested library to handle all the low-level stuff really does win out.
(Before you ask, some of the libraries you mention will merrily install themselves as servlets; this allows your code to just describe the business logic of the servlet and declare how mapping to the wire is done in abstract terms. That's just enormously easier.)
JAX-RS is a very well designed API that makes mapping HTTP requests to methods, extracting parameters from various parts of a HTTP request, handling content negotiating, and many other low level tasks very easy.
Using JAX-RS, mainly via Apache CXF, for roughly two years now, I'd always prefer it over plain Servlets.
Frameworks are used to make you task more easier. i agree that we can do the same thing by implementing servlets and then parse the url and then implement the basic logic.
Bu if you are using framework like jersey then u don't have to worry about those parsing patterns and other similar tasks. ServletContainer class will take care of this (parsing url in it's service method) and there are lots of other classes also which will make your task easier.
And one more thing we are taking only a one scenario (matching patterns) but when our requirements will grow the same code written by our own servlets will become more complicated and complex.
I would go with using Jersey or a library in this case, if it does the following (adds enough value):
the config for the URL is all self-contained within one file, with the source
there are no hidden config files or overly verbose configs (e.g. web.xml)
the parameters are nicely mapped to strongly typed variables (e.g. use of annotations)
it is not convoluted to get to the values of parameters (e.g. RESTlet)
the overhead for running the library is low (I have had bad experiences with reflection solutions in other libraries)
it is well documented
it is well adopted
In such a scenario, I find that using a library would add value to my project for the effort required to use it. Jersey does seem to mach the requirements quite adequately, although I have not given other frameworks enough investigation yet.
At work, we currently have a WSDL interface as well as a semi-RESTful interface that we're looking to expand upon and take it to the next level.
The main application runs using Servlets + JSPs as well as Spring.
The idea is that the REST and WSDL are interfaces for an API that will be designed. These (and potentially other things in future) are simply a method through which clients will be able to integrate with the interface.
I'm wondering if there are any suggestions or recommendations on frameworks / methodologies, etc for implementing that under-lying API or does it make sense simply to create some Spring beans which is called either by WSDL or REST?
Hope that makes sense.
Have a look at Eunicate it is great . You are using spring , Spring has had support of SOAP for a while and Spring 3 has support of REST (Creating and Consuming).
Your approach makes sense. Probably the most important advice is to make the external API layer as thin as possible. You can use Axis, Apache CXF, Jersey, etc. to handle the implementation of the REST or SOAP protocols, but the implementation of those services should just load the passed in data into a common request object, and pass that into a separate service that handles the request and returns a response object which the external API layer will marshall into the correct format for you.
This approach works especially well when you have a competitor providing similar services and you want to make it easy for their customers to switch. You just build a new external API that mirrors the competitors, and simply translates their format to your internal api model and provided your services are functionally equivalent, you're done.
This is a really late response, but I have a different view on this topic. The traditional way as we know it is to unmarshall xml to java and marshall java to xml. However if the wsdl changes then it would effectively be a structural change in the code which would again require a deployment.
Instead of the above approach if we list the fields mentioned in the wsdl in a presistent store, load the mappings in memory and prepare our structures based on these mappings we would have to have many less changes for this..Thus IMO instead of using existing libraries a configurable approach to unmarshalling and marshalling should be taken.
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.