We Keep Coding

Sample Request for a REST-API in Java or PHP

I am looking at extracting data from a survey tool using their API. Being fairly new to APIs, I went through their documentation, few videos and figured out a little of what's happening.
But along with the Method and Attributes, they also have a sample request in Java/PHP and a sample response. Now the sample response is the JSON file fomat I'm expecting back but what do I have to do with a sample response?
As in, from all the videos I have seen you call an API using a particular URL. What is this sample request used for? Is it for using it in your own code?
I know its quite a silly question but any input would be much appreciated.

Assume you have a system that manages "virtual machines" for you; and that offers an API like:
/system/create-new-virtual-machine
/system/{virtual-machine-id}/start
So: your client would first call the first API method to somehow define a new virtual machine (providing all the required data to create a configuration).
Obviously, when you create a new thing, that should result in a new URI; which you would use later on to make other calls. In our example, the create call would return 200 ... and give you the URI for the newly created vm within the result body.
Long story short: just think of your REST api as the interface of a component/module your code is dealing with. Some of the API operations just tell you "fine, I passed" ... but others will want to give you information back. And that is what you need the response body for.

how to consume a Restful Web Service (Restful API) in Java

I just want to know the high level steps of the process. Here's my thought on the process:
Assumption: the API returns JSON format
Check the API document to see the structure of the returned JSON
Create a corresponding Java class (ex: Employee)
Make Http call to the endpoint to get the JSON response
Using some JSON library (such as GSON, Jackson) to unmarshall the JSON string to Employee object.
Manipulate the Employee object
However, what if the API returned JSON is changed? it's really tedious task to exam the JSON string every now and then to adjust the corresponding Java class.
Can anyone help me out with this understanding. Thanks

You describe how to consume a json over http API, which is fine since most of the APIs out there are just that. If you are interested in consuming Restful HTTP resources however, one way would be:
Check the API documentation, aka. the media-types that your client will need to support in order to communicate with its resources. Some RESTafarians argue that all media-types should be standardized, so all clients could potentially support them, but I think that goes a bit far.
Watch out for link representations, and processing logic. media-types do not only describe the format of the data, but also how to process them. How to display it if its an image, how to run code that might be part of the message, how to layout onto the screen, how to use embedded controls like forms, etc.
Create corresponding Java classes. If the resources "only" describe data (which they usually do in API context), then simple Java classes will do, otherwise more might be needed. For example: can the representation contain JavaScript to run on the client? You need to embed a JavaScript engine, and prepare your class to do just that.
Make call to a bookmarked URI if you have it. There should be no hardcoded SOAP-like "endpoint" you call. You start with bookmarks and work your way to the state your client need to be in.
Usually your first call goes to the "start" resource. This is the only bookmark you have in the beginning. You specify the media-types you support for this resource in the Accept header.
You then check whether the returned Content-Type matches one of your accepted media-types (remember, the server is free to ignore your preferences), and then you process the returned representation according to its rules.
For example you want to get all the accounts for customer 123456 for which you don't yet have a bookmark to. You might first GET the start resource for account management. The processing logic there might describe a link to go to for account listings. You follow the link. The representation there might give you a "form" in which you have to fill out the customer number and POST. Finally, you get your representation of the account list. You may at this point bookmark the page, so you don't have to go through the whole chain the next time.
Process representation. This might involve displaying, running, or just handing over the data to some other class.
Sorry for the long post, slow day at work :) Just for completeness, some other points the client needs to know about: caching, handling bookmarks (reacting to 3xx codes), following links in representations.
Versioning is another topic you mention. This is a whole discussion onto itself, but in short: some people (myself included) advocate versioning the media-type. Non-backwards compatible changes simply change the media type's name (for example from application/vnd.company.customer-v1+json, to application/vnd.company.customer-v2+json), and then everything (bookmarks for example) continues to work because of content negotiation.

There are many ways to consume RESTful APIs.
Typically, you need to know what version of the API you are going to use. When the API changes (i.e. a different version is exposed) you need to decide if the new functionality is worth migrating your application(s) to the latest and greatest or not...
In my experience, migrating to a new API always requires some effort and it really depends on the value of doing so (vs. not doing it) and/or whether the old API is going to be deprecated and/or not supported by the publisher.

Which HTTP Method should I use for my REST Service method doing READ & WRITE?

As per RESTful services guidelines we should use GET for reading a resource, POST for creating a new resource, DELETE for deleting an existing resource etc.
But assume I am developing a RESTFul webservice, say OrderProcessing. In placeOrder(Order) method I have to read some tables like inventory, product details etc, insert some new rows into tables like order and order details and do updates like reducing the inventory level etc. Then what HTTP method should I use for placeOrder() method.
At the very high level we are creating a new resource(Order), so I thought POST is correct HTTP method to use.
But in general what verb should be used for method doing read/create/update of data inside same method?

I agree with your thinking that POST is appropriate here. Even though you are doing multiple operations, you can view this as a single create of your Order resource. As for the other operations, I would view those as internal details that you are not exposing to the consumer of your service.
Edit - Taking this a step further, This assumes that you have defined Order as your resource, and the POST body contains a representation of this resource. And to be totally RESTful, if the POST results in the creation of a new Order, then HTTP 201 is the appropriate response code. See section 9.5 of http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html for more details.

Definitely POST. You can rule out GET and DELETE for obvious reasons, and you would only want to use PUT for an idempotent operation. Since you're reducing inventory, you can safely rule out PUT as a viable option.

jQuery AJAX to call Java method

Using jQuery AJAX, can we call a specific JAVA method (e.g. From an Action class)
The returned data from that Java method would be used to fill in some HTML code.
Please let me know if this can be done easily using jQuery (like it does in DWR)..Also for multiple data points in HTML, do we need to make multple AJAX requests?

The simple answer is you map your ajax calls to urls, which are in turned map to methods in your java code. The Ajax -> URI mapping happens on the client side (which ever js framework you are using, and the URI -> specific handler mapping happens within the java application)
What java framework are you using? There should be very clear and simple documentation on how to do this. For standard Java EE mappings (meaning you are not using any frameworks like Spring or Roo) I found this on google: http://javapapers.com/servlet/what-is-servlet-mapping/
"For multiple data points in HTML" I assume you are talking about having multiple parts of the html update. You can do this with multiple requests, or you can do it with one request. If you do the latter, the server needs to return all the data you need to update the dom appropriately.

It's not as transparent as with DWR--DWR handles making JavaScript look like Java. With jQuery you'll get JSON (or just HTML if/when it's easier that way). It's still pretty straight-forward, though. You'd send the Ajax request to a URL, rather than having it look like a local method call.
I'm not sure what you mean by "multiple data points in HTML" -- you get back whatever data you get back, and you can do with it whatever you want. If the response has all the data you need, then you wouldn't need to make multiple requests.

How do RESTful and SOAP Web Services differ in practice?

I am implementing web services for a PHP application and am trying to understand what both standard web services and RESTful web services have to offer.
My intent is to write wrapper code to abstract away the web service details so that developers can just "instantiate remote objects" and use them.
Here are my thoughts, perhaps some of you could add your experience and expand this:
RESTful Web Servcies
are basically just "XML feeds on demand", so e.g. you could write wrapper code for a client application so it could query the server application in this way:
$users = Users::getUsers("state = 'CO'");
this would in turn get an XML feed form a remote URL
$users could be made into a collection of full User objects, or
left as XML, or
turned into an array, etc.
the query script ("state = 'CO'") would be translated into SQL on the server side
RESTful Web Services are in general read-only from the view of the client, although you could write code which could use POST or GET to make changes on the server, e.g. passing an encrypted token for security, e.g.:
$users = Users::addUser($encryptedTrustToken, 'jim',$encryptedPassword, 'James', 'Taylor');
and this would create a new user on the server application.
Standard Web Services
Standard Web Servcies in the end basically do the same thing. The one advantage they have is that client can discover their details via WSDL. But other than that, if I want to write wrapper code which allows a developer to instantiate, edit and save objects remotely, I still need to implement the wrapper code. SOAP doesn't do any of that for me, it can do this:
$soap = new nusoap_client('http://localhost/test/webservice_user.php?wsdl', true);
$user = $soap->getProxy();
$lastName = $user->lastName();
but if I want to edit and save:
$user->setLastName('Jones');
$user->save();
then I need to e.g. handle all of the state on the server side, SOAP doesn't seem to hold that object on the server side for each client.
Perhaps there are limitations in the PHP SOAP implementation I am using (nusoap). Perhaps Java and .NET implementations do much more.
Will enjoy hearing your feedback to clear up some of these clouds.

They are different models... REST is data-centric, where-as SOAP is operation-centric. i.e. with SOAP you tend to have discrete operations "SubmitOrder", etc; but with REST you are typically a lot more fluid about how you are querying the data.
SOAP also tends to be associated with a lot more complexity (which is sometimes necessary) - REST is back to POX etc, and YAGNI.
In terms of .NET, tools like "wsdl.exe" will give you a full client-side proxy library to represent a SOAP service (or "svcutil.exe" for a WCF service):
var someResult = proxy.SubmitOrder(...);
For REST with .NET, I guess ADO.NET Data Services is the most obvious player. Here, the tooling (datasvcutil.exe) will give you a full client-side data-context with LINQ support. LINQ is .NET's relatively new way of forming complex queries. So something like (with strong/static type checking and intellisense):
var qry = from user in ctx.Users
where user.State == 'CO'
select user;
(this will be translated to/from the appropriate REST syntax for ADO.NET Data Services)

I'm echoing what Marc Gravell mentioned. When people ask me about REST (and they usually have an idea about SOAP and SOA), I will tell them REST = ROA as it is resource/data oriented, it's a different paradigm and therefore has different design concerns.
For your case, if I'm reading you correctly, you want to avoid writing the wrapper code and need a solution that can store objects and their attributes remotely (and having them completely hidden from the developers). I can't really suggest a better solution.. Umm, let me know if either of these ever come close to meet your requirements:
EJB3 / JPA
CouchDB (REST/JSON)
Let me know too if I've interpreted your question wrongly.
If we compare XML-RPC and SOAP, the latter will give you better data types handling, for the former although you will be dealing with simpler data types but you will have to write a layer or adapter to convert them to your domain objects.
yc

Soap is just a set of agreed upon XML schemas blessed by a standards group. It's strength is that it was designed for interoperability and it supports many enterprise-class features. Soap on any platform will not provide the operations you are looking for. You need to design & implement the service contract to get those features.
Sounds like you want remote objects which neither Soap or REST are particularly good for. Maybe you'd be better off looking at XML-RPC.

The key differences are basically tooling.
Many of the high end SOAP stacks shroud the vast bulk of the SOAP infrastructure from the developer, to where you are working pretty much solely with DTO's/Documents and RPC.
REST over HTTP puts more of that burden upon you the developer (negotiating formats [XML, JSON, HTTP POST], parsing results [DOM, maps, DTO marshalling, etc.]).
Obviously, you can write a layer of logic to make dealing with this detail easier. And some REST frameworks have arrived to make this easier, but at the moment, it's still a task on your TODO list when you wish to use or consume such services.

My feedback is that if you want remote state, you are not talking about web services. I don't know about any contemporary model that deal with remote state. I think that if you need remote state you are on your own ( without religion to follow ). Just throw xml from here to there and don't mind the theory.
I have to add that remote state is evil. Avoid it if you can.