I have looked around a bit on stackoverflow as well as google, but couldn't find any good tool that can document SPRING-REST api. Tried using enunciate, but it barfed out on spring annotations it couldn't recognize. Does anyone know of a good tool for documenting a spring RESTful api ?
Typically you need not document your REST API. Your clients should be provided with the specification of the media type you are using (think Atom or OpenSearch for example) and only rely on the information given there.
As soon as you document anything about a specific service, you are coupling your clients to that documentation (and that service). The result being that your service's ability to evolve is now limited by the amount of out-of-band information the clients have baked in their code (based on your API description).
IOW - when was the last time you needed a service API description to make your feed reader talk to an AtomPub service?
Jan
P.S. The theoretical backgrounds I summarized in [1]. Look specifically at the difference between HTTP Type I/II and REST. And Roy's [2] is a MustRead on this.
[1] http://www.nordsc.com/ext/classification_of_http_based_apis.html
[2] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
Just document everything that needs to be documented from a client developer perspective. And please don't take advice like "you need not document your REST API" seriously. This is a pedantic guidance and not useful in the real world.
Every successful API out there is well documented from client developer point of view. Any API that is hung up on pedantic notions is bound to turn off client developers.
See Chapter 14 of my "RESTful Web Services Cookbook" (http://shop.oreilly.com/product/9780596801694.do) for some examples.
Try using Swagger. It provides few of its own annotation that work well with Spring MVC rest annotations.
Related
As a developer, I prefer spring restdocs. But as a consumer of the documentation, I find the swagger live documentation to be very compelling. Here's the ubiquitous example: http://petstore.swagger.io/
Is there a way to document my rest apis with spring restdocs but generate live documentation like the swagger petstore with it? If so, how do you do this?
No, it's not possible out of the box. REST Docs is intended to be extensible so you could add the functionality yourself but it would be a significant undertaking.
I'm the lead of the REST Docs project and support for live documentation is of interest, but it's not a particularly high priority at the moment. In my experience, live documentation can be useful as a playground but does a poor job of actually documenting a service. My focus at the moment is on producing accurate and well-structured documentation. Using REST Docs with Slate can give you a big jumpstart on the latter if you're looking for something more guiding than Asciidoctor's blank canvas.
I am working on an application which is built in .NET and Java. The Java component contains the complete Rule base using Redhat BRMS suite. The .NET client (UI and desktop based applications) will be consulting the Java Rule engine and sending/receiving the JSON data. The decision which has been taken is to expose the Rules engine (Redhat BRMS 6.0.0 using Drools) as a REST based API. I have come-up with the following design approaches:
Write a REST controller in Spring framework and service classes for calling BRMS.
Write a simple REST controller using JBOSS proprietary RESTSY or JAXRS.
Write a Camel adapter and wrap the REST calls behind the Camel and let the Camel talk to Drools.
Wrap REST behind SOAP based webservices.
I want to ask which one would be the better approach for designing such as System.
Any other thoughts are welcome.
As might be obvious from https://github.com/gratiartis/sctrcd-payment-validation-web and https://github.com/gratiartis/qzr my general preference is for exposing my Drools business rules using REST APIs in a Spring application.
The only alternative I consider in the above list is 4, where the API is exposed through a SOAP web service. Albeit definitely not wrapping a JSON REST service! A well-designed Spring application can expose functionality through both REST and SOAP APIs with very little effort.
I have usually exposed via SOAP when working with .NET clients. Firstly, the .NET tooling has excellent support for generating proxies based on WSDL that you have defined. Secondly, the WSDL forms a well-defined contract which both you and the client developers must obey. Having a strict contract can be very useful in preventing arguments. Although if your interface is simple, it may not be so much of a benefit.
The other key reason is that the WSDL does not change unless you change it deliberately. A REST JSON API may seem quick to develop, thanks to Jackson generating everything for you. However, it can expose your internal object model (and dependencies!), meaning that unless you are careful, what seems like a trivial change to an internal model can make private data visible and can break clients.
All that said, if you can keep the API reasonably simple and have a good relationship with the .NET devs (perhaps you're one of them), then going with the Spring REST API would be my recommendation. Feel free to steal code from the github repos if it can help you get started!
btw - If you were to consider Camel, it's worth noting that there is a Drools-Camel component which does quite a bit of the work for you.
In my view,
I would go with the option 1. This is the simplest and easiest approach.
Option 2 may be second choice.
Option 3 - Looks like if there are some routing rules you could choose. Again its could make it complex.
And definitely not option 4 to make it complicated with SOAP.
I need to write integrations to multiple external web services. Some of them are SOAP (have WSDL), some of them pretty much ad hoc - HTTP(s), authentication either by basic auth or parameters in URL (!), natural-language like XML which does not really map nicely to domain classes..
For now, I've done the spike integrations using Spring Web 3.0 RestTemplate and binding using JAXB2 (Jaxb2Marshaller). Some kind of binding is needed because domain classes need to be cleaner than the XML.
It works, but it kind of feels bad. Obviously this partially just because how the services are built. And one minor issue I have is naming of RestTemplate as services have nothing to do with REST. This I can live with. JAXB2 feels a bit heavy though.
So, I'm looking for some other alternatives. Ideas? I'd like to have a simple solution (so RestTemplate is fine), not too enterprisey..
While some of your services may be schemaless XML, they will still probably have a well-documented API. One of the techniques that the Spring folks seem to be pushing, at least from the web-service server side, is to use XPath/XQuery for retrieving only the information you really need from a request. I know that this may only end up being part of your solution, but I'm not sure that this is a situation where one particular binding framework is going to meet all your needs.
If I understand correctly you have 1 application that has to make calls to various external (web) services by use of different technologies. The first thing that comes to mind is to have some intermediate level. While this could be something as elaborate as en ESB-solution, my guess is that is not what you're looking for.
You could for example achieve this intermediate level by having a class hierarchy with at its top an interface 'Consumer'. Method to be implemented: doConsume() and so on.
If you look into it you'll probably have the opportunity to make use of several design patterns like Strategy or Template. Remember to be pro-active and try to ask a few times 'What if ..' (As in: what if they need me to consume yet another service? etc.)
If JAXB feels too heavy there are other API's to be found:
Axis
JAX-WS
CXF
other
It'll depend on the situation which one would be better. If you run into troubles with any of them I'm sure you'll be able to find help here on SO (and from people who have more hands-on experience with them than me ;-)
I've bounced around Java and C# the last several years but now want to get up to speed with Web Services (RESTful). I used to be a master of J2EE circa 2003, but have since got side tracked into all kinds of stuff. I've worked through a couple of NetBeans tutorials (my IDE of choice) but they don't seem to expose the nitty gritty. I enjoy seeing how things exactly work, building an app from the byte array up.
Although I've touched a couple of frameworks, I've most enjoyed working with Java EE proper to understand the base case before the sugar of Spring/Hibernate is added.
Does that make sense? I am looking for a book or tutorial that really builds up your knowledge piece by piece so that you understand everything, not some Rails-like toolkit for rapid development.
Thanks-in-advance,
Guido
I'd start by doing a review of HTTP, since in practice this is a fundamental building block of REST web services, and it gets you into the right mindset for what comes next.
Next, think about how you'd structure the URIs for various resources. Martin Fowler wrote a good article on this topic. Various java frameworks for creating web services try to make it easier for you to map requests to specific methods, and even to map parts of requests (including path elements, query parameters, and the entire request body) straight into your object model. But all of this just help with the identification and manipulation of resources through URIs.
Next, if your resources are related, then think about hypermedia controls. You're probably used to putting <a href=""> links in web pages, and you certainly wouldn't want people to hardcode or bookmark every single URL in your website. How does the same idea extend to web services?
Next, think about actually moving data between client and server. JSON or XML? URI element or query parameter? Again, lots of java frameworks exist just to make this easier -- for example, Jackson and Gson for REST, JAXB for XML, etc. -- but the problem of dealing with HTTP-based requests and responses is very similar to the one that your average servlet container solved years ago.
Finally, consider security. For example, username/password or OAuth? HTTP or HTTPS?
There are lots of other details, but these topics should keep you busy for a while.
Have you checked out Jersey yet? This is the Java reference implementation of JAX-RS. There is a great community around this project, and the main author is available via mailing lists and forums and has personally answered questions of mine for some gnarly situations I ran into. The jersey site has a lot of great links to get you started from a variety of angles, depending on what you're interested in learning.
RestifyDayTrader has very good details of how to build a RESTFul service.
Java implementation can be found at Restified Trader
Java Web Services is a good read on learning Web Services.
we are looking to create a web service to provide functionality for stateless data transactions on a single data store. the service will be consumed by applications running several potential environments - at least windows .net, php, and java, but possibly more.
what is the best format to use for passing data back and forth? "best" i would consider to be the format in the sweet spot between ease of consumption and strongly typed content. at one end, SOAP tells you everything you need to know about the service but requires a good deal of processing on the client side to parse. On the other side would be JSON for its minimalist format and ease in parsing, but obviously the client needs to have a very good idea about what data it should be expecting.
would one of these solutions be more ideal than the other? is there another format to consider?
as a follow up, what frameworks can you recommend to implement the format on the server side? our server OS is linux, so php or java would be the preferred solution, but an alternate platform like node.js could also be considered. something like WCF in the .NET world would be ideal since you can write the business logic once and let the presentation framework make it available in several formats simultaneously.
As #WhiteFang34 recommended, REST is a very accessible protocol to you. Even though it is not a standard, it is widely used and well documented in most modern programming languages.
REST merely defines what each HTTP method should do, but you still need to decide what format to use. JSON and XML are the most popular ones, but from my experience JSON is a lot less troublesome to work with in most cases.
If you use the WCF REST 4.0 template you can get a REST and SOAP endpoint on the same service. Its easy as pie. I think that RESTful is the best way to go for most things.
The nice thing about REST is that its easy to consume. It can be a bit more work to consume, but it works very cleanly. SOAP is harder to consume, but once you get it wired up most frameworks work great with it. Myself, I have never had much luck with using SOAP services across many platforms.
You should consider using REST. It's popular for web services. I recommend reading A Brief Introduction to REST that goes over application-to-application communication with REST. There's also RESTful Web services: The basics. There are plenty of REST solutions to choose for with Java:
Apache CXF
Jersey
RESTEasy
Restlet
Spring (docs)
There's also the JAX-RS API that most of them adhere to (all of these except Spring).