One of the key points of building a RESTful API is HATEOAS. Now, Jersey offers a linking ability which is quite good (see this link). But I have seen the draft of the HAL Specification and it seems to be a well thought piece of work.
I am interested if there is some lib that makes it easy to adhere to HAL in Jersey. I have seen the references mentioned in the draft like https://github.com/HalBuilder. But I am using direct POJO marshalling and I do not know how to mix that with Halbuilder.
So, is there already some lib that incorporates HAL into Jersey? Or maybe I can use some kind of filter to enhance the generated POJOs manually? If yes, can someone give me a clue where to look next to accomplish this?
I can't find any direct support for this in Jersey, but there should be ways to customize the marshaller that Jersey uses to convert your POJO's to JSON. (either by using HalBuilder, or create some HAL-compatible code of your own)
If you use Jerseys JAXB based JSON support, take a look at BootstrapTypeConverterTest in the jettison source code which demonstrates how a converter can be used to cusomize JSON output. Unit-testing conversions to/from JSON should be a simple task and jettison-project has good examples to look at.
If you use Jerseys "POJO Support"-method, take a look at JacksonHowToCustomSerializers for a similar example on how to create your custom serializers.
(If JAXB is involved, you can also do cool things like processing custom annotations.)
You probably have a pretty good idea of how your objects (input) looks like and what JSON code (output) you expect, so creating unit tests for these conversions should be a relatively simple task.
Even if this is not really an answer, I had not enough characters to put it in a comment :)
If you're really new to REST, I think you're beginning probably in the wrong way. I don't know exactly your requirements, but if you only want to learn, begin with an easy REST service, use Web API from .net or something similar in Java (a simple servlet would be enough) and try to implement a service which only uses the tools delivered by http (the verbs, the request header and payload, the response message). REST API design rulebook from Marc Massé could be a good reference to learn. Create your own communication protocol with POJOs or POCOs and once you really what you can do REST and how it works, you can use a framework to ease your work.
If you begin with a framework you may miss the essence of the concept...
I hope it helps!
It's very little that's required to adhere to HAL. I suggest you roll your own mini-library where you wrap your POJOs in HAL-objects. This way you get the code the way you like it and it will be way simpler than HalBuilder.
Related
I have read the swagger definitions and the format and understood that swagger definition is used to describe the APIs.
Would it be better to write the swagger definition and then the API? or to write the API first and then the swagger? I have no experience with this and I would like to write a REST API and a swagger file for an application.
I don't think the order really matters. Both methods are given legitimacy in the Swagger Getting Started Guide. The key thing is that one should be generated from the other, so you don't have to manually maintain both.
In the comments, cricket_007 has already mentioned that tools exist to generate the web service skeleton from the swagger definition. Using these tools, it would make sense to write the swagger definition first. This is the Top Down approach from the getting started guide.
From the Swagger getting started guide linked above, you can see that there are also tools available to generate Swagger docs from java code, provided you are using a particular framework like JAX-RS. This is the Bottom Up approach.
It comes down to personal preference. If you are the kind of person that would rather not "couple" your code base to Swagger and make sure that your application does not depend on Swagger to work, then the bottom up approach is best. However, if you want to fully embrace the Swagger tool chain and really "buy in" to it, then the top down approach is probably the best.
Also, if this is for educational purposes, then think about what you want to learn about. If you want to learn about writing JSON REST APIs from scratch (or using something like JAX-RS), then the bottom up approach will teach you more. However, if your goal is to learn as much as possible about Swagger, then the top down approach will be better.
I like the TDD approach to documenting your restful api with spring-rest-docs. However, I love "API Playground" feature enabled by swagger specification. I wish there was a way to get best of both worlds.
Is there a way to build swagger2 specs from spring rest docs? may be via building custom request/response preprocessors.
Do you have any thoughts or recommendations?
There's not out-of-the-box support for this in Spring REST Docs at the moment. The issue that you opened will track the possibility of adding such functionality. In the meantime, your best bet would be to look at writing a custom Snippet implementation that generates (part of) a Swagger specification.
Typically, a Spring REST Docs snippet deals with documentating a single resource, whereas a Swagger specification describes an entire service. This means that the Swagger specification Snippet implementation will need to accumulate state somehow, before producing a complete specification at the end. There are lots of ways to do that (in memory, multiple files that are combined in a post-processing step, etc.). It's not clear to me that one approach is obviously the right one so some experimentation would be useful. If you do some experimentation, please comment on the issue that you opened with your findings.
I'm really confused everytime I come around this question, what characteristics would help one choosing SOAP over REST or the other way around?
I mean, besides the fact that REST has a compact format compared to SOAP, and the other "minor" or "technical" differences, what are the "obvious" differences that make one of them more suitable for a project and not the other?
Just for the record, I have read all of the other questions (1|2|3|4) regarding this matter on Stack Overflow, and not one of them answered my question.
The difference between REST and SOAP is fundamental, yet they're not that dissimilar. Ultimately, you still need to transfer exactly the same information in order to perform a particular abstract operation. It's entirely easy to make REST rather low-performing by choosing poorly what information to return, and SOAP with MTOM can transfer large binary chunks efficiently. There's even the possibility to use non-XML encodings and connected transports (e.g., XMPP) with SOAP that can make it more efficient than REST.
So don't worry about that!
A much more relevant thing to think about is that SOAP continues to have significantly more advanced tooling support in some languages, and that other languages strongly prefer REST. For example, if you want a Java client for your service, you'll be able to get going with SOAP in minutes: just put the WSDL location through a tooling engine and you've got yourself a basic client. On the other hand, if you're working with a Javascript client then you'll absolutely prefer to deal with the REST interface; Javascript works great with REST.
A key thing to note here is that you can have your service support both SOAP and REST at once (you might need to put them on different endpoints, but that's not very onerous). I do this with a service I support (using Java and Apache CXF) and the overhead of doing both is minimal: the key is that I need a clean abstract interface behind the scenes that both the SOAP and REST interfaces use.
If you just want a simple, visual guide to help you measure SOAP and REST against your applications requirements...
Vijay Prasad Gupta has put together a simple, helpful flow-chart.
Direct link to flow chart:
https://drive.google.com/file/d/0B3zMtAq1Rf-sdVFNdThvNmZWRGc/edit
Link to article:
https://www.linkedin.com/pulse/20140818062318-7933571-soap-vs-rest-flowchart-to-determine-the-right-web-services-protocol-for-your-needs
SOAP is a form of RPC and REST is architecture style that can scale with the web.
REST concerns about the following (copied from RESTful Web Services)
Addressability
Statelessness
Representations
Links and Connectedness
The Uniform Interface
Two great books on REST and have some discussions on the topic that you are interested in.
REST in Practice
Restful Web Services
Could anybody clarify the process of consuming aspx webservices in iOS? I have already tried JSON framework but now, need to create an app that consumes .net webservices in XML format. I need both to post some data to, and get data from the server. I already read about existing XML parsers for iOS that I found (here)
The question is do I need to do additional setup, like wrapping my query strings in SOAP or smth, in order to communicate with webserver? Would it be sufficient to use only one of mentioned libraries in the link or do I need additional stuff?
UPDATE: I found one tutorial on web (here) that demonstrates how to consume web services using Json-framework. Also, I found another one that demonstrates it using NSXMLParser (here). I'm not not very familiar with WSDL and SOAP, so any detailed explanation on how to implement would be desirable :). In both of these examples you just have to construct a request string in xml format and execute it, and that's it. Both examples actually bypasses the heavyness of SOAP and WSDL, so I was wondering do I have to know and do more that just construct a request string, execute it and get response?
While wsdl2objc is out there (as noted by #Girish Kolari), the truth is that there's no easy answer. I've never successfully gotten wsdl2objc working well for something that I couldn't have done more easily by hand. You will need to learn SOAP and WSDL. That's just a fact of life if you can't get access to a REST interface. In my experience, your best bet for simple SOAP access is to do it by hand, and your best bet for somewhat complicated SOAP access is gSOAP. Your best bet for very complicated access is to redesign something so it's not so complicated, ideally in REST. SOAP is a giant pain that some languages (C#) shield you from. ObjC does not shield you from it, so it continues to be a giant pain.
Yes, SOAP leaves a bad taste in my mouth.
Striving to ship a well documented application, I'm looking for a good way to describe a REST API for my Grails Application users.
I know that REST calls should be simple enough to be described by examples, but it doesn't feel formal enough.
I've spent a couple of hours looking for a solution suggested by other Grails users, but didn't find a neat solution besides a recommendation to use WADL or WSDL 2.0
This looks like a good direction, but there must be a simple way to do it in Grails.
I'd appreciate some guidance for a process to generate a REST API based on my model objects preferably with the ability to filter or control the exposed fields, plus, a nice graphical way to present it (something like the XSD Eclipse plugin)
Thanks!
Guy
I would suggest to avoid WADL or WSDL for API documentation, you can see this question where I explained my reasons: Why the slow WADL uptake.
WADL or WSDL are usually used for automatic client code generation, they are not human readable documentation. I don't think WADL or WSDL are very useful for a user to figure out how to consume the resources correctly.
I prefer the good old html documentation, for example I like the way twitter documented their API
If you insist on automatic generation of resources documentation I can recommend on the ATOM service document. Many REST framework can generate it automatically based on the resources annotations. (e.g. Apache Wink)