RESTful Web Services Cookbook

Subbu Allamaraju

Mentioned 9

Provides information on designing RESTful Web services for client and server applications, covering such topics as Web linking, content negotiation, Web caching, queries, security, and compatibility.

More on Amazon.com

Mentioned in questions and answers.

I'm looking for a book or any other resource that will help me learn how to create RESTful APIs in Java. Looking on Amazon, I saw that there are several solutions for RESTful Java, but I'm looking for the one that is tailored to a novice.

Looking forward to getting your advices/opinions, thanks!

My recommendation would be this one:

alt text

I don't think I can point to only one resource but I would take a path (which you can customize based on your level of understanding of REST). I'm somebody who would like to get my concepts real clear first and then think about the tools to implement the concepts.

Obviously, I haven't provided a single resource, but something in the lines I've provided would serve well, IMO.

I found REST in Practice to be the best book covering different styles of REST architectures. It's also far more practical in its advice than many other books (I wasn't impressed by RESTful Web Services as I think it lacks focus).

I'm creating a RESTful API that will process a number of user interactions, including placing orders using stored credit cards.

In the case of a successful order, I'm returning a 200 OK, and in the case where the order request is malformed or invalid I'm returning a 400 Bad Request. But what should I return if there is a problem during the actual processing of the order?

  1. Client POSTS order to server for a user resource. If user does not exist, 404 Not Found is returned.
  2. Order format and information is validated. If not valid, 400 Bad Request is returned.
  3. Order is processed. If the order is successful, a 201 Created is returned for the order. If an unexpected error is encountered, a 500 Server Error is returned.

The last step is the problem - what do I return if the order doesn't complete for any other reason? Possible scenarios could include:

  • Product is sold out
  • User maximum order limit reached
  • Credit card transaction failure (insufficient funds, etc.)

This doesn't seem like it would be appropriate for either a 400 or 500. If anything I could see it as a 400 if there's no better code - the request was invalid according to the business rules. It just doesn't seem accurate.

Edit: Also found this existing discussion of the same topic. All of the answers there seem to point to using status codes for this type of violation, with some discussion between using 400, 409, or the 422 extension.

You should use 400 for business rules. Don't return 2xx if the order was not accepted. HTTP is an application protocol, never forget that. If you return 2xx the client can assume the order was accepted, regardless of any information you send in the body.


From RESTful Web Services Cookbook:

One common mistake that some web services make is to return a status code that reflects success (status codes from 200 to 206 and from 300 to 307) but include a message body that describes an error condition. Doing this prevents HTTP-aware software from detecting errors. For example, a cache will store it as successful response and serve it to subsequent clients even when clients may be able to make a successful request.

I'll leave it to you to decide between 4xx and 5xx, but you should use an error status code.

I am a fairly experienced (mid-level) developer that has spent quite a bit of time working on the backend of many web-based projects. Rarely getting into the ui/display aspects. However, I am now a lead on a project that is in the process of taking an api to a service architecture using an asp.net mvc rest architecture. I have not problem doing this and have written many of these services already. however, I find myself wondering about the parts "hidden" by IIS/WAS and MVC.

What I am hoping to find is a good tutorial that explains what happens from the point a web page (or webservice) is requested to the point it is received by the web page or application takes over. I want to know how IIS (or any other webserver) knows what to do with a request. (One thought was a tutorial for developing your own webserver.)

I realize this is probably a large subject that I don't necessarily need to know all of to be an "expert" web developer. However, it certainly can't hurt and I also am experienced enough to separate the wheat from the chaff.

Thanks in advance!

If you are developing a RESTful web service and want to learn more about HTTP I strongly suggest reading RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity.

REST recommends that queries (not resource creation) be done through the GET method. In some cases, the query data is too large or structured in a way that makes it difficult to put in a URL, and to address this, a RESTful API is modified to support queries with bodies.

It seems that the convention for RESTful queries that require bodies is to use POST. Here are a few examples:

Queries don't modify the internal state of the system, but POST doesn't support idempotent operations. However, PUT is idempotent. Why don't RESTful APIs use PUT with a body instead of POST for queries that require a body?

NOTE: A popular question asks which (PUT vs POST) is preferred for creating a resource. This question asks why PUT is not used for queries that require bodies.

No. PUT might be idempotent, but it also has a specific meaning. The body of the request in PUT should be used to replace the resource in the URI.

With POST no such assumptions are being made. And note that using a POST request means that the request might not be idempotent, in specific cases it still might be.

However, you could do it with PUT, but it requires you to jump through an extra hoop. Basically, you could create a "query resource" with PUT, and then use GET immediately after to fetch the results of this query resource. Perhaps this was what you were after, but this is the most RESTful, because the resulting query results can still be linked to. (something which is completely missing if you use POST requests).

I have a website (call it siteA) I used php and Zend, I am trying to implement an api to access the restricted areas of my site(SiteA) from another(call it SiteB).

I would like to be able to authenticate user on siteB with SiteB credentials, have an html iframe to siteA where the user has been Authenticated via the API.

I am new and don't really know if I am headed in the right direction.

So far I was thinking about using a restful api, and outside the frame the user is validated but in the frame the user is not.

Suggestions and help? And my code is as follows:

----- SiteB user/index.php ----

<html>
<body>
<?php
  $postdata = http_build_query(
   array(            
    'userid' => 'someid',
    'key' => 'somekey',
    'public' => '1'
   )
  );

$opts = array('http' =>
  array(
    'method'  => 'POST',
    'header'  => 'Content-type: application/x-www-form-urlencoded',
    'content' => $postdata
   )
 );

$context = stream_context_create($opts);
file_get_contents('https://www.siteA.com/api', false, $context);
?>

<iframe src="https://www.siteA.com/" width="950" height="700"></iframe>
</body>
</html>

----- SiteA ---------

<?php

class ApiController extends Zend_Controller_Action
{

    public function init()
    {
        /* Initialize action controller here */
        $this->_helper->viewRenderer->setNoRender(true);
        $this->_helper->layout->disableLayout();
    }


    public function indexAction() {
        if($this->getRequest()->isPost()){        
            $data = $this->_request->getPost();
            $this->_authenticateApi($data);
        }
        else{
            //error
        }

}
 public function _authenticateApi($data){
    $db = Zend_Registry::get('db_local');

    $authAdapter = new Zend_Auth_Adapter_DbTable($db);

    $authAdapter->setTableName('sometable');
    $authAdapter->setIdentityColumn('id');
    $authAdapter->setCredentialColumn('key');


    $authAdapter->setIdentity($data['id']);
    $authAdapter->setCredential($data['key']);

    $auth = Zend_Auth::getInstance();
    $result = $auth->authenticate($authAdapter);

    if($result->isValid()){
        if($data['public'] == "1"){
            Zend_Session::rememberMe(1209600);
        }else{
            Zend_Session::forgetMe();
        }
        return true;
    } else {
        return false;
    }
}

I have faced this problem recently. Is there a reason you must use an iframe? It feels kind of hackish to me.

There are lots of ways to do this, but in my reading, it seems like a Best Practice is to make the API require clients to authenticate using HTTP Auth Basic, and to use HTTPS (an SSL Certificate) to encrypt the connection. The API does not manage sessions in this case! Every request contains the Auth Basic header, just like a regular web browser would do if you were directly browsing your API.

With your SiteB then, when the user logs in, you'd store their credentials in your $_SESSION or somewhere similar, and use them every time you make an API request.

RESTful Web Services Cookbook, by Subbu Allamaraju, is a great book I read recently that discusses this and other important RESTful API details.

By the way, it's not really RESTful unless your client is able to figure out the URLs all by itself just given an entry URL and knowledge of the media types the API features. Search for HATEOAS for more.

Also, if you try to do all this in JavaScript and SiteA and SiteB do not share the same domain, you may be forced to use JsonP to handle your API requests. While it can be done, IMHO it's undesirable. Use Zend_Http_Client in your SiteB's PHP code to do all the API communication. This way you get around the domain name issues. This also keeps your API hidden from prying eyes (right-click, view source!) and minimizes the potential for any cross-browser compatibility issues to interfere with your site's core functionality.

i'm new with web service programming and i want to create,using netbeans 6, a restful web service using Jersey over a Grizzly server and then a client javascript in order to use this web service through a browser. So i started learning more on restful web service and i read a lot of guide over the web, then i started learning more on grizzly and jersey by reading jersey user's guide http://jersey.java.net/nonav/documentation/latest/index.html. I succesfully follow the tutorial to create the helloword example resource. So i created all the resources needed for the job and tested successfully with the browser...but i'm still confused: in particular i want know how i can create a static homepage which can be used by the users to select what is the desired resource. Can you give me some tutorial or example?? Thanks to all!

(Moreover i want to learn more on grizzly server and creating jersey restful web service, can someone give me a useful guide or book??)

So, the key to understanding RESTful web services is to understand the HTTP protocol more thoroughly. That's what makes it easier than (and often preferable to) RPC style services epitomized by SOAP. When you pull down a static web page, for example, you can think of it as a limited "web service" which serves only GET requests. In order to make a static web page which "selects resources," you would only need to provide URLs to the resources in question, as long as they're accessed via GET, because that's the same HTTP method used for retrieving web pages (and therefore is the default method for web browsers). If you want to access other types of resources, such as sending POST requests, you can use a form; other than that (with PUT, DELETE, HEAD, OPTIONS, etc.) you'll want to use Javascript or a more programmatic API for accessing the HTTP resources.

There are many good books in this space, and I've found these particularly useful:

The first two approach REST in theory and practice; they are more about the concepts than specific technology. The third addresses the Java standard for RESTful services as defined in JSR 311, of which Jersey is the reference implementation. The last is more of an "enterprisey" book, but it's been useful to me from the approach of designing a system of web services, as opposed to one-off service resources.

Which are the rules you would use to design a routing schema properly in ASP.NET MVC?

I think most of the REST URL design guidelines apply, but do you know a good article/guide about it in web applications?

When to use path, when get parameters, when post parameters, etc...

Thanks.

I am trying to write a simple ruby script to collect an array of JSON objects from a RESTful web service. I have read a lot of documentation that suggests I need to create an HTTP GET request, but I haven't seen an example of how to pass parameters to only return the objects I need. (I.e. I need to retrieve ONLY JSON objects with a particular name/value pair)

Essentially I am trying to query a database that can return information in JSON format, but I only want to select objects that meet certain criteria, and store that in an array.

I have been able to retrieve ONE JSON object, by looking at the NET requests in chrome developer tools when I manually search for one of these objects using a web GUI, but I cannot figure out how to generate a request for multiple objects.

Sorry if this is a dumb question, I am new to both ruby and REST.

Thanks!

we are just in the beginning of a new project. We want to use Grails on server side and GORM pages(for html pages rendering and JQuery support) and GWT(for rich gui backend interface). Later we planned to extend our application by devices for Android or Iphone. Therefore we planned to use a RESTful(with JSON) interface for all service access.

Now is my question is this approach a little bit overkill? Because we are now struggling to find the right structure for our REST interface. Of course we want to setup the interface so that I can be reused by all clients instead of providing e.g. GWT specific RPC service and the JQuery html interface is rendered by GORM only.

  • Is this approach a little bit overkill?
  • What is the easiest way to define a RESt service?(just look what for data I need, name the service and go for it?)
  • How would you suggest to put the rendering on HTML side? Only forward in the action to the appropriate view(gorm) and let JQuery only communicate via the REST service and rendering of JSON data instead of using gorm specific form logic?

Thanks for your help

Doesn't sound like overkill if you're planning to create mobile device clients. There are plenty of good resources on how to implement REST in Grails (I've been primarily following the book Grails in Action and this link, as well as this guide to RESTful services).

As for HTML rendering, in a simple web-only app I'd say just pass GORM objects into your normal views, that would probably be easiest. But GWT does have good support for services, plus if you use your services in the web front end, this will give you a complete set of usage scenarios for your REST services that you'll be able to use on the mobile device apps.